javadoc: @version and @since

java documentation javadoc
Sasha picture Sasha · Feb 23, 2009 · Viewed 64.8k times · Source

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

Answer

dhable picture dhable · Feb 23, 2009

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.

Related questions

How can I reference the value of a final static field in the class?

Using JavaDoc, how can I reference the value of a final static field in the class? I want the ??? in this example replaced by the value of the field STATIC_FIELD. /** * This is a simple class with only one static …

Read More
How to add package level comments in Javadoc?

I am using CheckStyle, FindBugs, and PMD to validate my Java code. I have fixed almost all the bugs caught by these tools. I am not able to understand how to write "package comment" which is a bug caught by …

Read More
How to use @value tag in javadoc?

I am using a class with private constructor instead of an enum (this is a requirement). And now I am trying to add javadoc tags to document each public static final entity. 1) What is prefered place to put javadoc tags: …

Read More