javadoc: @version and @since

Question

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%

Solution 1

The @version tag should be the current version of the release or file in question. The %I%, %G% syntax are macros that the source control software would replace with the current version of the file and the date when the file is checked out.

The @since tag should be used to define which version you added the method, class, etc. This is your hint to other developers that they should only expect the method when they run against a particular version of the package. I would consider these uber-important parts of the documentation if you're shipping your code as a library intended for someone else to use.

Solution 2

Explained well in an article from Oracle, How to Write Doc Comments for the Javadoc Tool.

@version

…classes and interfaces only.

At Java Software, we use @version for the SCCS version. See "man sccs-get" for details. The consensus seems to be the following:

%I% gets incremented each time you edit and delget a file

%G% is the date mm/dd/yy

When you create a file, %I% is set to 1.1. When you edit and delget it, it increments to 1.2.

Some developers omit the date %G% (and have been doing so) if they find it too confusing -- for example, 3/4/96, which %G% would produce for March 4th, would be interpreted by those outside the United States to mean the 3rd of April. Some developers include the time %U% only if they want finer resolution (due to multiple check-ins in a day).

The clearest numeric date format would be to have the date formatted with the year first, something like yyyy-mm-dd, as proposed in ISO 8601 and elsewhere (such as http://www.cl.cam.ac.uk/~mgk25/iso-time.html), but that enhancement would need to come from SCCS.

@since

Specify the product version when the Java name was added to the API specification (if different from the implementation). For example, if a package, class, interface or member was added to the Java 2 Platform, Standard Edition, API Specification at version 1.2, use:

/**
 * @since 1.2
 */

The Javadoc standard doclet displays a "Since" subheading with the string argument as its text. This subheading appears in the generated text only in the place corresponding to where the @since tag appears in the source doc comments (The Javadoc tool does not proliferate it down the hierarchy).

(The convention once was " @since JDK1.2" but because this is a specification of the Java Platform, not particular to the Oracle JDK or SDK, we have dropped "JDK".)

When a package is introduced, specify an @since tag in its package description and each of its classes. (Adding @since tags to each class is technically not needed, but is our convention, as enables greater visibility in the source code.) In the absence of overriding tags, the value of the @since tag applies to each of the package's classes and members.

When a class (or interface) is introduced, specify one @since tag in its class description and no @since tags in the members. Add an @since tag only to members added in a later version than the class. This minimizes the number of @since tags.

If a member changes from protected to public in a later release, the @since tag would not change, even though it is now usable by any caller, not just subclassers.

Solution 3

I don't see how they are mutually exclusive. One is used to define version, and the other is used for describing since when the method is there. For example:

/**
 * Does Whatever
 * @version 1.2.3
 * @since 1.2.0
 *
 */
public void myMethod() {
    // .......
}

Regarding the characters you mentioned, they seem proprietary, and in any case I have no clue what they mean.

Solution 4

@version will be record every edit.[1.3.21]

@since is mean since which release version will be support this interface or etc.[1.3] Yuval Adam is interesting, but this is not the standard, java doc 's purpose is everyone can understand.

View more solutions

Comments

[Admin]

First of all, @since indicates version # and NOT the date, as since which version it is available. Please correct if I am wrong here. Thanks

[Admin]

Thanks for the explanation. If version is the current release, then all classes will consist that #. is Isn't @version is redundant in that case, as customer as well as a developer knows which version he/she is using I don't see @version in the actual java api. Thx

[palantus]

Sasha: I believe @version is hidden by default, like @author.

[Admin]

Thanks and interesting, but java says different. Is what you're suggesting a common practice against Java's doctrine?

[Admin]

I just don't see the point of including it, as a developer, naturally, should know what version he checked out from the cvs and used, especially, if the tag is shared among all classes in the project.

[palantus]

I've never used @version, personally.

[Rob Kennedy]

Sasha, imagine a scenario where two versions are being developed concurrently. I work an at least three versions of the same code, and it could be nice to know which version's file I'm looking at, and which version's documentation I'm reading.

[dhable]

To add to Rob's comment, I generally find them useful when looking at the JDK docs. There was a time when I was a foolish, young developer and developed my project using JDK1.4 on Windows when deployment used 1.3. I spent the morning of deployment trying to fix exceptions from missing methods.

[Aritz]

True, @Since seems to define a version number. Please, review this answer.

[Urosh T.]

The @version %I% %G% seems not to be working in 2018?

[UdayKiran Pulipati]

can you give me example / link how %I% gets incremented each time you edit and delget a file works ?