Javadoc: Do parameter and return need an explicit type description

Question

When Javadoc'ing, I don't know whether you should explicitly say whether the parameters are of type String or int. For example

/**
 * This method does something
 * @param foo an object of type Foo
 * @param abc the number of doors, of type int
 * @return the number of windows, of type int
 */
public int doSomething(Foo foo, int abc) {
    // Do something
}

I use eclipse, so when I look at the user end of a Javadoc, everything has a type description, and eclipse tells me when I used the wrong type reference.

So, should I include type descriptions as above, or does Javadoc/compiler take care of that for me?

Answer 1

No, there's no need, the JavaDoc tool parses the Java code and gets the types from there.

This article on the Oracle Java site may be useful: How to Write Doc Comments for the Javadoc Tool

From the @param part of that article:

The @param tag is followed by the name (not data type) of the parameter, followed by a description of the parameter. By convention, the first noun in the description is the data type of the parameter. (Articles like "a", "an", and "the" can precede the noun.) An exception is made for the primitive int, where the data type is usually omitted. Additional spaces can be inserted between the name and description so that the descriptions line up in a block. Dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash.

Parameter names are lowercase by convention. The data type starts with a lowercase letter to indicate an object rather than a class.

...which sounds like it disagrees with my statement above. That's just poor writing, as the examples it then gives make clear:

@param ch the character to be tested

@param observer the image observer to be notified

@param x the x-coordinate, measured in pixels

It's also clear from the detailed examples.

Answer 2

I agree it's not very well written, but I think the answer is sort of yes, in that the article is saying it is a convention for each param name to be almost immediately followed by if not its actual data type then a description of its data type ("By convention, the first noun in the description is the data type of the parameter."), i.e.

@param ch the character to be tested

@param observer the image observer to be notified

except that for ints, we are told, a description of the data type is generally omitted.

So they don't need it, but it is a convention to provide it.