ansaurus

Question

Answer 1

+1 A:

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 January 8, 2005
 *
 */
public void myMethod() {
    // .......
}

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

Yuval A 2009-02-23 16:54:16

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

2009-02-23 16:55:51

I've always used @since to denote the date when I'm working on non-API code

MrWiggles 2009-02-23 16:57:26

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

2009-02-23 17:02:24

Answer 2

+5 A:

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.

Dan 2009-02-23 16:55:22

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

2009-02-23 16:59:49

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

Michael Myers 2009-02-23 17:02:07

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.

2009-02-23 17:03:46

I've never used @version, personally.

Michael Myers 2009-02-23 17:07:23

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.

Rob Kennedy 2009-02-23 18:44:56

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.

Dan 2009-02-23 21:06:59

ansaurus

tags:

views:

answers:

javadoc: @version and @since

related questions