JavaDoc Interface comments [closed]

Question

I have an interface A which has methods x, y and z. I am commenting the class this way:

/**
 * 
 * A.java
 * Interface class that has the following methods.
 * 
 * @author MyName
 * @since mm-dd-yyyy
 */

public interface A {

    //method description for x
    void x();

    //method description for y
    void y();

    //method description for z
    void z();
}

Is it right or should I add other things to the CLASS COMMENTS?

Answer 1

No, you haven't specified any JavaDoc comments for the methods. How is someone using or implementing the interface meant to know what the methods are meant to do? You should use proper JavaDoc descriptions:

/**
 * This method fromulgates the wibble-wrangler. It should not be called without
 * first saturating all glashnashers.
 */
void x();

Bear in mind that unlike most JavaDoc which is aimed at callers, interface documentation has two audiences: callers and implementers. You need to be clear about what both sides can expect and how they should behave. Yes, this is hard to do well :(

EDIT: In terms of the top-level comments:

• Personally I'd get rid of the @author tag, as it's rarely useful IMO. (Usually looking in source control is more appropriate...)
• Unless you actually have a meaningful versioning policy (not just dates), I'd get rid of the @since tag.
• There's no point in stating the source file
• A description of "Interface class that has the following methods" is meaningless and contradictory (as an interface isn't a class). Whoever's reading the JavaDoc will already be able to see the list of methods. You should be trying to provide extra information here.

Just like for normal class documentation, interface documentation should state the purpose of the type - its role in the grander scheme of things, perhaps an example of how it's expected to be used, etc. Look at examples in the JDK for generally-reasonable JavaDoc.