Java Documentation - @return and @param

Question

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?

Answer 1

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.

Answer 2

Those things are javadoc tags. Full reference of how to use they you can find here: http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html

But basic example for those two you have mentioned above will look like this:

/**
 * Adds two values.
 *
 * @param operand1 - first numeric value for the ADD operation
 * @param operand2 -  second numeric value for same purposes
 * @return sum of two operands
 */
 public int add(int operand1, int operand2) {...}

Javadocs are always used before method or variable or class / interface

Answer 3

Why not start by looking up what JavaDocs are?

http://en.wikipedia.org/wiki/Javadoc

An example of how they are used is like this.

/**
 * Gets the id of the player.
 *
 * @param someParam you'd put a description of the parameter here.
 * @return the id of the object.
 */
public int getId(int someParam) {
    return this.id;
}

Answer 4

This is Javadoc you are talking about:

/**
 * Subject line
 *
 * <p>Description of the method with optional {@code code} and {@link Object links to Javadoc}
 * </p>
 *
 * <pre>
 *    raw input
 * </pre>
 *
 * @param foo first arg
 * @return a bar
 * @throws SomeException if bar goes wrong
 * @see someOtherMethod()
 * @since 2.2.2
 * @author me
 */
int doSomething(final int foo)
    throws SomeException
{
    // etc
}

The javadoc tool (and targets which use this tool in various build systems such as gradle and maven) will generate HTML files from that.

Would I have to put more descriptions afterwards?

Before it, in fact, as a convention. And only if you deem it necessary.

Also, is there something as too much documentation?

Yes.