felix-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Felix Meschberger <fmesc...@gmail.com>
Subject Documenting API evolution
Date Thu, 14 Oct 2010 06:48:22 GMT
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

Mime
View raw message