Enhanced @since in Javadocs
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?