Java Documentation - @return and @param


I'm wondering how to document code with @return and @param ...? I'm sort of guessing that I would do something like

@return(whatever the method is returning)
@param(parameters that the method is taking in)

Would I have to put more descriptions afterwards? Also, is there something as too much documentation?


Answers:


The Javadoc style guide explains the intended uses of these tags. @param describes a parameter and @return describes the return value. (There are several other useful tags.)

Remember that Javadoc generates documentation from your code, not just from your comments. The signature of the method will appear in the output -- therefore, don't tell the readers stuff they already know. The purpose of your documentation is to supply the additional semantics not expressed in the signature. Is that numeric parameter constrained to a particular range of values? Are there any special return values (like null)? Document the contract.

You ask if there is such a thing as too much documentation. Yes, there is. API reference documentation is most useful when it tells the readers all and only what they need to know to properly use the interface. So fully document the contract, but say nothing abut how your code implements this interface. Link to other elements of the API (such as other classes or interfaces) if they directly bear on the part you're documenting (for example if somebody needs to use SomeFactory to obtain an instance of SomeThing, the class you're documenting).

This isn't to say that you should never write anything longer than a few sentences; sometimes an interface is complex and requires more explanation. Consider whether that explanation belongs in a package overview, the top-level documentation of a class or interface, or a specific member. If you find yourself cutting and pasting an explanation in several places, that may be a sign that you need to address it at a higher level instead.