Has anybody got a link to a good example of java doc comments (actually a good example of normal commenting would be good as well)?
I am currently starting the main commenting of my code and find it quite difficult to express what I want well and to determine how much detail to go into and what to do and not to do.
I also find it a bit stressful because I get the feeling that this sort of thing depends on the markers preferences and so I might spend a whole lot of time for very little gain.
Oh by the way, I have read the Sun "How to write doc comments for Javadoc" article and found it really good but would like a few more examples.
Jacques's example is good.
and I have a few comments in addition to those offered by Jacques.
if the method return void,then you should not have a @return tag.
last,you should use a IDE such as "IntelliJ IDEA" or "JBuilder" to check your javadoc
hope this helps
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.
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.
I strongly recommend DocCheck. The following is from Sun:
"DocCheck is now available at:
The Sun Doc Check Utilities consist of the doc check doclet (DocCheck)
and a utility package. DocCheck is an extension to the Javadoc tool
that reviews Javadoc comments in the source code, identifying gaps
and irregularities. It produces an HTML report that separates serious problems from trivial ones, and makes "suggestions" in the form of templates that show you what is needed."
Something that I've found to be fairly useful for getting ideas about how to do javadoc is the source for Java itself (or more accurately J2SE). Not only does it give you an idea of what to write, but it also provides some tips on formatting. My javadoc looked like a mess until I started doing some of the things I saw in the Java source. One last benefit (maybe) is that if you have a doubt and want to document it in choices.txt citing the Java source could be a good supporting argument for doing what you did.