I would say that for most purposes @author is unwanted noise. The user of your API shouldn’t – and probably doesn’t – care, or want to know, who wrote which parts. And, as you have already stated, SVN already holds this information in a much more authoritative way than the code can. So if I was one … Read more
First of all, you should remove the original eclipse template because it is just noisy junk. Either put meaningful docs in or don’t put anything at all. But useless restating of the obvious using IDE templates just clutters the code. Second, if you are required to produce javadoc, then you have to make the comment start with /**. … Read more
The official guidelines on this are pretty clear. The functional differences are: {@link} is an inline link and can be placed wherever you like @see creates its own section In my opinion, {@link} is best used when you literally use a class, field, constructor or method name in your description. The user will be able to click through to the javadoc … Read more
Yeah, it is quite vague. You should use it whenever for readers of the documentation of your method it may be useful to also look at some other method. If the documentation of your methodA says “Works like methodB but …”, then you surely should put a link. An alternative to @see would be the inline {@link …} tag: … Read more
How about the JDK source code, but accessed through a 3rd party like docjar? For example, the Collections source. That way, there’s no big download.
Javadocs are a specific comment format used to generate external documentation for your code. You shouldn’t be converting regular comments to Javadoc. For example: See this technical doc for more details. If you do want to convert the comments, though, you would have to do it manually like you said. There isn’t a specific tool … Read more