JavaDoc Interface comments

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?

Solution 1

Yes you should write proper Javadoc comments for your interfaces to clearly specific the motivation behind the interface and what the contract is for both callers and implementors.

Take a look at some of the interfaces in the JDK code for examples, like java.util.List

Solution 2

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.

Comments

[FranXh]

I am not asking about the methods comments, I am asking about the class commetn. I know how to commen methods I am not sure about Interface Classes only

[Jon Skeet]

@user1181847: Well if you give an example which fails to document the methods, and ask whether you're doing the right thing, what do you expect?

[FranXh]

I am asking if I am doing right the class comment. I have specified that in my question

[Jon Skeet]

@user1181847: It wasn't really clear what you meant - but see my edit for what I think you were after.

[Paŭlo Ebermann]

Actually, I hate it when I use a library in a version different that what's the newest version documented on the web site, and this is without any version tags indicating if the method was already there forever. (But of course, this means you should have a versioning policy if you are writing and publishing a library.) Alternatively, put Javadoc for all versions of the library on your website.

[Jon Skeet]

@PaŭloEbermann: Yes, if you're going to do versioning properly, then document it - but just putting the date is rarely useful, IMO... especially if you then add methods to the interface without noting it...