@version JavaDoc Tags

Another comment that came up in my code review yesterday was why I had an @version 1.0 in my JavaDocs for the class I wrote. My reasoning was that, according to Sun's documentation, the author and version tags are required (though obviously it won't throw a compiler error or anything like that, it may throw an error in Sun's Doc Check tool). This launched a discussion about whether the version tag should indicate revisions in the version control system (in our case svn) or release tags of the software. The practice varies from shop to shop, but my initial reaction (despite Suns' practice) considered tags to be logical, since that would indicate API changes. However, @since I suppose is what really should be used, and a colleague pointed out that changing all the classes to match whatever release is current hides the fact that some classes (particularly abstract data classes) may not have changed at all.

My own conclusion out of this was to use svn keyword substitution to set the tags. I used my favorite svn client, TortoiseSVN, to set the properties. You can either set it as a global setting (which will add the property to new and imported files) or on particular files (need to do for files that already exist). This matches Sun's practice of tying @version to their source control system.

While on the subject of JavaDoc, I was mocked for pointing out a spelling mistake in a JavaDoc comment. In my view, JavaDoc is a special class of comment. Whereas internal comments can contain all the mistakes and profanity you want, JavaDocs are something your client might actually see, and thus should be treated just the same as a mistake like

System.out.println("Pleez enter your name: ");
String name = bufferedReader.readLine();

Am I wrong?
As a quick way of setting Subversion properties for use in Javadoc, I usually create a script with this in it:

for file in $(find ${1}/*/src -maxdepth 10 -name *.java); do if [ -z `svn proplist ${file} | grep -o "svn:keywords"` ]; then svn propset svn:keywords "Author Date Revision Id" ${file}; fi; done