Skip to main content

Enhanced @since in Javadocs

3 replies [Last post]
Joined: 2004-11-17

Maybe we need a better syntax for @since Javadocs tags. For example, take constructors for RandomAccessFile. They both get a string as the second argument. This string specifies the access mode of the file to be opened. In JDK 1.4 the allowed modes are r, rw, rwd, rws. However, in JDK 1.3 the allowed modes are r, rw only.

Now, this can not be detected by any modern IDE that looks only at the @since tag. Neither can it be detected by some futuristic IDE that might compare Javadocs for different JDK's. There are currently three ways to find out:

1. Read the Javadocs yourself, which can be quite tedious for any big project.
2. Read the JDK source, which is nice on itself, but not feasible.
3. Deploy your application and find the hard way.

Number 3 has happened to me lately, as we compile and check against JBoss in JDK 1.4.2, but then deploy in WebLogic in JDK 1.4.1 and WebSphere in JDK 1.3.1. The WebSphere deployment failed, of course, because i have used rwd, which caused me to spend about half a day rebuilding the whole project because of one character.

Maybe there could be an easy way to specify @since tag for each parameter?


Reply viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.
Joined: 2004-11-23

In fact it is questionable whether Sun should have changed the method at all. If a contract specifies a restriction, e.g. only [i]r[/i] and [i]rw[/i] are allowed as values, then clients can expect this restriction to remain true.

When writing unit tests, we don't just test the inputs we expect to succeed, but also the inputs we expect to fail. So if Sun would have had such unit tests on the RandomAccessFile class in Java 1.3, then these tests would have [i]failed[/i] in Java 1.4...

Instead, Sun should IMHO have provided new methods or constructors with a different contract. E.g. a factory method.

Joined: 2003-06-28

What is your proposed solution?

Java doesn't allow backward-incompatible changes in method signatures, which roughly means that other parameters, checked exceptions, return values won't be changed. Therefore, @since can only be practically be applied to method or class.

What you present as necessary to be marked with @since is a part of specification that has changed. Do you propose to mark parts of specification with release attributes? How do you see this in practive, could you please provide the Javadoc example?

BTW, your idea fits well into the JSR 260, don't hesitate to post it and other Javadoc ideas to this JSR.

Joined: 2004-11-17

We can use additional tag, say @changed with two "arguments", parameter name and the version number.

For example

[b]@changed mode 1.4[/b]

Then an IDE can paint the parameter named [b]mode[/b] in some color to indicate that some characteristic of this parameter (for example valid values) has changed in JDK 1.4. Even better, and IDE will flag it as a warning if i'm using JDK 1.3, forcing me to take a look at this particular call to decide if i'm using JDK-compliant value.