Documenting API evolution

[Felix Meschberger <fm...@gmail.com>]

Hi all,

To document in JavaDoc the evolution of the API of a class we generally
(and should) use the @since tag. Traditionally, this tag is provided
with the first release version of the library included the modified API
(e.g. the added method or constant).

With OSGi where we not only have the module/bundle level versioning but
also the independent versioning of the exported packages, just listing
the library version in the @since tag seems a bit wrong.

I started listing the actual package export version as the primary value
of the @since tag adding also the bundle version first exporting this
package version. For example:

    /**
     * ...
     *
     * @since 3.1.2; Web Console Bundle 3.1.4
     */
    public static final String CONFIG_PRINTER_MODES =...

Does this make sense in terms of "good practice" ?

Regards
Felix

Re: Documenting API evolution

[Premek Brada <br...@kiv.zcu.cz>]

  On 14.10.2010 14:59, Richard S. Hall wrote:
>  On 10/14/10 2:48, Felix Meschberger wrote:
>> <snip>
>>      /**
>>       * ...
>>       *
>>       * @since 3.1.2; Web Console Bundle 3.1.4
>>       */
>>      public static final String CONFIG_PRINTER_MODES =...
>>
>> Does this make sense in terms of "good practice" ?
>
> Certainly using the package version makes sense. I think the bundle 
> version makes less sense since the packages could be re-packaged into 
> other bundles, like we do with the OSGi API and others. But it doesn't 
> harm anything.

I agree.  Also I'd think that using bundle symbolic name in the tag 
might be safer than the descriptive name because it is more stable.

Premek


-- 
Premek Brada (Ing et MSc, PhD)
   Lecturer in Software enginering, Webmaster
   Department of Computer Science and Engineering
   University of West Bohemia, Pilsen, CZ
   <<  brada at kiv.zcu.cz | www.kiv.zcu.cz/~brada/ | +420-377-63-2435>>

Re: Documenting API evolution

["Richard S. Hall" <he...@ungoverned.org>]

  On 10/14/10 2:48, Felix Meschberger wrote:
> Hi all,
>
> To document in JavaDoc the evolution of the API of a class we generally
> (and should) use the @since tag. Traditionally, this tag is provided
> with the first release version of the library included the modified API
> (e.g. the added method or constant).
>
> With OSGi where we not only have the module/bundle level versioning but
> also the independent versioning of the exported packages, just listing
> the library version in the @since tag seems a bit wrong.
>
> I started listing the actual package export version as the primary value
> of the @since tag adding also the bundle version first exporting this
> package version. For example:
>
>      /**
>       * ...
>       *
>       * @since 3.1.2; Web Console Bundle 3.1.4
>       */
>      public static final String CONFIG_PRINTER_MODES =...
>
> Does this make sense in terms of "good practice" ?

Certainly using the package version makes sense. I think the bundle 
version makes less sense since the packages could be re-packaged into 
other bundles, like we do with the OSGi API and others. But it doesn't 
harm anything.

-> richard

> Regards
> Felix