问题
I am a Java developer, and I'm interested in improving the quality of my Javadoc comments in the code and programs I write to make it more comprehensible and easier for other developers to implement.
I've read lots of articles, including those from official sources, and I try to follow the guidelines stated in the book "The Elements of Java Style", but despite this, and after searching extensively online, I can't seem to find a practical way to compare my existing Javadoc(s) to model examples and maintain best practices for Java API documentation.
回答1:
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.
Also i can share you some stuff below
A great read on writing javadoc is at the sun site at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html
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.
回答2:
In addition to the Sun's (now Oracle) documentation at http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html I would recommend the "Item 44: Write doc сomments for all exposed API elements" from the "Effective Java" book by Joshua Bloch, 2nd ed. pp.203-208. This is a 6 page recommendation/tips with several practical examples.
回答3:
A better way may be if you post an example method you wrote, then we can help you write Javadoc for that. If you are just asking for general suggestions, then it may be hard to outdo the book.
回答4:
You can use @link parameter for 'VoucherStore'
Example:
@return {@link VoucherStore} type Concrete Object based on storeType parameter
instead of
@return returns VoucherStore type Concrete Object based on storeType parameter.
来源：https://stackoverflow.com/questions/5401636/how-to-write-good-javadoc-comments