Technical tips for writing great JavaDoc

Question

What are your technical tips for writing great JavaDoc?

I'm looking for things beyond the standard "Explain the function well" content-based tips. We all know that! (right?)

I'm interested in things like these:

• What tags should definitely be a part of one's JavaDoc, and which ones are not worth remembering?
• When do you use @see vs. {@link}?
• Is it always necessary to use @param for obvious parameters?
• How do you prevent the description of a method from re-iterating the @param and @return text?
• When is it appropriate to include HTML in JavaDoc?

Finally, can anyone point to a good, succinct list of JavaDoc tags?

Answer 1

• I'd say the most important ones are @author, @deprecated, @inheritDoc, @param, @return, @throws. But you should have a look at all tags, just in case.
• We use @link when used as explanations inside the text, and @see as a list of references.
• "Is it necessary to use @param for obvious parameters?" No.
• Use {@inheritDoc} whenever appropriate.
• Here is a list of tags.

Answer 2

Additionally to your specific question, I would recommend you to always remember when you write your javadoc the audience you're targeting ( the API users that is ) and what kind of details you put there.

You must specify behavior and NOT implementation details.

For a very good explanation of why, who better than an expert on the subject, Joshua Bloch

Here is the talk How To Design A Good API and Why it Matters

It's a little lengthy but it worth it.

With this in mind you can write an useful @return tag that does not leak the implementation details.

Answer 3

I think that unless you're building a library for widespread use, there's not much need for things like @param (which is often clear from context and naming). I actually find them more of a hassle than not because they're things that I'm liable to forget to fix in the refactoring stage.

More useful to me are things like:

-How does the function behave in edge cases? what does it do if you give it a null? Will it ever return a null?

-Under what conditions does it throw it's listed exceptions

-What assumptions is it making about the state of the input objects?

Then again, this is probably because these are the kinds of things I tend to need to go back and check for, and most of the javadocs I've written have been either for myself or for co-workers on small teams. The larger the intended audience, the more rigorous I'd feel I needed to be.

Answer 4

Peer review.

Try and find someone outside your team (a customer) and ask them what they think about your JavaDoc.

The customer is always right.

Answer 5

A great read on writing javadoc is at the sun site at http://java.sun.com/j2se/javadoc/writingdoccomments/

The best thing I've learned from that text is probably that your class level javadoc should start with "Provides". This forces you to think about what that class provides to your program (or the world). It's not uncommon for me to redesign software because writing javadoc made me think "hey, this is not needed here!".

Other practical tips: When a getter is interesting, try to write it in the @returns tag. Not doing so might mean that you type stuff twice, once in the javadoc, and once after the @return tag.

An the best tip: If you don't know what to write, DONT. the Javadoc parser does a great job of automatically generating getter javadoc for example, but it only does it when you didn't add a /** */.

Javadoc should desccribe WHAT your method does, not HOW.

Javadoc is not your todolist. I've tried it, but for larger projects, it simply doesn't work.

Answer 6

Another important tip is that if your are writing an abstract class or interface, make sure to visually separate the text for audiences that will use the method on objects from this hierarchy, and audiences that will override the method.

Too many framework javadocs present clients with nuggets of the form "subclasses should know that X...". Make it very easy for subclasses to see those, and for those who are not subclassers to avoid them. Don't ever mix them without sufficient vertical distance.

Answer 7

I did quite a bit of research on this issue at one point, and I found Javadoc best-practices documentation to haphazard, and disorganized. In particular, I discovered these six links from Sun (1 2 3 4 5 6). It seems to me like this material could be better organized and condensed somehow.

Also, as an aside, the HTML that is generated by javadoc is badly out of date. It is not even valid HTML. I realize there are javadoc doclets out there, but it would be nice to see some official support from Sun. JavaFX has some promising documentation technology, but cannot be used for Java code, as far as I can tell.