java - 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%

Answer 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.