Hey gang,
I stressed out about the "code" and "link" tags in my Javadoc comments. I put some link tags where I felt they added value, and tried to surround my datatypes or explicit return values (like true and false from boolean functions) with code tags.
Here is an excerpt from my choices.txt regarding this issue:
Javadoc all methods and classes
-------------------------------
I have included Javadoc style comments for all methods and classes, including inner and anonymous classes. This will make it easier for a new developer to understand the code, as well as assist them if they need to increase the visibility of some of the methods. They won't have to do Javadoc for them in that case.
I didn't Javadoc all variables, just public and protected ones. In many instances, I simply used a regular comment to explaining related variables in one comment block. It's less cluttered that way. Furthermore, code is commented using standard comments where I felt it truly adds value. Many of the method names imply what is happening, but the comments are there to assist.
I thought about placing @see tags in concrete classes that implemented interface methods, and leaving it at that. However, I looked at the Java source, and saw that there is explicit Javadoc comments on the interface and on the concrete class. I emulated this by placing the comments in both my interfaces and my concrete classes so that readability would be improved.
Every package has its own brief package.html file for completeness.
Javadoc links
-------------
I was going to start putting every reference to other classes in my Javadocs as links, but I decided against this. I did this where I felt it added value, and relied on Javadoc method signatures to link to the references.
Hope that provides some more information for your documentation decision.
Cheers,
Jason