Checkstyle "Expected @param tag for 'id'" error

Question

I am using checkstyle in my codebase, http://checkstyle.sourceforge.net/, and I am having a question regarding JAVADOC.

I have static functions like this:

 **
 * @param id
 */
public static void getName(final String id) {
 }

where checkstyle complains about

Expected @param tag for 'id'

When I give a description like

@param id id

then it works fine, but I do not want to give a description for each param and return. Is there any alternative to fix this?

Answer 1

You are right - this warning means that you don't have a description of a parameter. If you don't want to describe the parameter why bother mentioning it? Your current JavaDoc is pointless and only occupies priceless editor space.

Either remove the parameter completely from the JavaDoc (I guess it's meaning is obvious from the context) or document it properly. And

/**
 * id The id
 */

is not a proper documentation.

Answer 2

Why bother running checkstyle if you're going to ignore it?

I largely agree with @Tomasz Nurkiewicz' answer, except that I would definitely document it.

The meaning of final String id may be obvious. To you. For now. The method getName may also be obvious — for now.

When I look at it I have no idea what it does, or what sort of "id" I need to pass in. Does it get the user's full legal name? Whatever name they entered? Their [last, first] name? What sort of id String do I need to pass in? An application internal ID number/code? You don't have any javadoc for what the method itself does either.

/**
 * Gets the indicated user's full name as entered when they registered.
 * @param id The application internal id generated when the user registered.
 * @return "void" ???  How do you get a name if it returns VOID?
 */
public static void getName(final String id) {
    ...
}

I'd declare this as public static String getName(...) because how do you get the name if it doesn't return anything? If it does something else, like put the name somewhere you can get it later then (1) this shouldn't be named "getName" and (2) you definitely need to document that fact in your javadoc.

Answer 3

You can fix it by change your comment

/**
* this is comment of function 
* @param id **this is id of table**
* @param username **this is name of user need for login**
*/

Please focus to ** {text} ** to fix this bug. Thanks