javadoc: @version and @since

[sasha]

Hello

Is there a reason to include both @version and @since as part of a
class?

They seem to be mutually exclusive.

Also, what does %I% and %G% mean, and how to set/use them?

@version %I%, %G%

thanks

 

[Lew]

Theoretically, you use '@version' to specify the current version
of the file, and '@since' to specify what was the current version
when a specific class/method/field was first defined.

And @version needs not use the same meaning of "version" than @since.
For instance, look at java.lang.StringBuilder. In the JDK-1.6 source,
java/lang/StringBuilder.java contains in the class JavaDoc both
'@version 1.11, 11/17/05' (which probably means that this is the
eleventh internal variant of that class implementation) and '@since 1.5'
(which states that StringBuilder was first defined in JDK-1.5). Here,
'@version' talks about version numbers for StringBuilder only, whereas
'@since' is about the JDK as a whole.

        --Thomas Pornin

 

[Lew]

Thomas Porninwrote:

Theoretically, you use '@version' to specify the current version
of the file, and '@since' to specify what was the current version
when a specific class/method/field was first defined.

I see @since used to specify the version of the system or subsystem in
which the artifact was introduced. I have never seen a statement as
to what either one means "officially"; each shop defines for itself
how to use these tags.

And @version needs not use the same meaning of "version" than @since.
For instance, look at java.lang.StringBuilder. In the JDK-1.6 source,
java/lang/StringBuilder.java contains in the class JavaDoc both
'@version 1.11, 11/17/05' (which probably means that this is the
eleventh internal variant of that class implementation) and '@since 1.5'
(which states that StringBuilder was first defined in JDK-1.5). Here,
'@version' talks about version numbers for StringBuilder only, whereas
'@since' is about the JDK as a whole.

The Javadoc tool documentation tells us that the @version tag

[a]dds a "Version" subheading with the specified version-text
to the generated docs when the-version option is used.
This tag is intended to hold the current version number of the
software that this code is part of (as opposed to @since,
which holds the version number where this code was introduced).

This implies that both @version and @since reference the same
versioning scheme, contrary to Sun's usage for StringBuilder. It also
waves a magic wand over what they mean by "the software that this code
is part of", though the wording suggests weakly that it's something
larger than the artifact itself.

<http://java.sun.com/javase/6/docs/technotes/tools/windows/
javadoc.html#@version>

My take on all this is use the tags for whatever you want, but do so
consistently.

 

[Lew]

Also, what does %I% and %G% mean, and how to set/use them?

Those are SCCS tags and not meaningful outside of version-control
systems that use them.

In VC systems that do use them, they are expanded automatically by the
system. CVS uses RCS tags; those are delimited with dollar signs
($). One might conceivably expand @version with $Revision$.

Since those revision-control tags only matter to developers of the
source, and Javadocs are intended for *clients* of the source, I don't
see much value in using them for @version.

 

[Stefan Ram]

Is there a reason to include both @version and @since as part
of a class?

(I am not answering your question.)

Reading the subject of this thread, I became aware of this
similarity:

»@author name-text Adds an "Author" entry
@version version-text Adds a "Version" subheading«

-- JavaDoc 2009

»@author The name of the author or authors.
@$VER: The version information«

-- AmigaGuide 1992

 

[Roedy Green]

s there a reason to include both @version and @since as part of a
class?

There have quite different purposes. See
http://mindprod.com/jgloss/javadoc.html
--
Roedy Green Canadian Mind Products
http://mindprod.com

One path leads to despair and utter hopelessness. The other,
to total extinction. Let us pray we have the wisdom to choose correctly.
~ Woody Allen .

 

[blue indigo]

The Javadoc tool documentation tells us that the @version tag

[a]dds a "Version" subheading with the specified version-text
to the generated docs when the-version option is used.
This tag is intended to hold the current version number of the
software that this code is part of (as opposed to @since,
which holds the version number where this code was introduced).

This implies that both @version and @since reference the same
versioning scheme, contrary to Sun's usage for StringBuilder. It also
waves a magic wand over what they mean by "the software that this code
is part of", though the wording suggests weakly that it's something
larger than the artifact itself.

<http://java.sun.com/javase/6/docs/technotes/tools/windows/
javadoc.html#@version>

My take on all this is use the tags for whatever you want, but do so
consistently.

For what it's worth, our shop here uses both tags, with the product's
version number, for the one I'm working on currently 3.0.7. (No, it's not
Firefox. ) Build numbers and other internal revision-control metadata
are kept separately in non-doc comments in the source and in various
places.

I have no idea whether this is typical in the wider industry, however.