Javadoc comments

[henryswanson]

I'm confused as to the purpose of three javadoc comments.

/**
 * What's this for?
 */

package group.subgroup

import some.stuff;
import some.extra.stuff;

/**
 * And this one?
 */

public class Foo {
    
    /**
     * Finally, this one?
     */
    
    //methods and their comments (i get how those work)...
}

And where do things like author, version, date, and copyright go?

[keang]

The first one is generally used for disclaimers, copyright info etc.
The second one contains the class description and often some example code on it's use. It is also where the author, version no. etc are normally put.
The third one could be either a comment for a declared variable, a constructor or a method. It all depends on what code follows it.

[henryswanson]

Okay, thank you!

[dlorde]

Remember that comments in the body of the code should clarify or explain when the code itself is necessarily obscure. Well-written code should require a minimum of comments.

Good code is its own best documentation. As you're about to add a comment, ask yourself, "How can I improve the code so that this comment isn't needed?" Improve the code and then document it to make it even clearer...
S. McConnell

Programs must be written for people to read, and only incidentally for machines to execute...
H. Abelson and G. Sussman

[henryswanson]

Alright, I went back and looked at the example I saw, and the third comment was not above a method or variable, but above another comment. It went like this:

public class Matrix {
    
    /**
     * The Matrix class throws a NonMultipliableException when two matrices cannot be multiplied,
     * but catches it internally and returns null.
     */

    /**
     * Constructs a new Matrix with dimensions x by y.
     */
    some constructor code...

    other methods...
}

Why would that comment be inside the class? Wouldn't it be better where the class description was?

[ProgramThis]

Yes, it would, plus the comment will not show up in the right place should you do it like that when you create JavaDocs.

If you are going to do arbitrary comments inside of a class that do not go to anything, you are better served using regular multi-line comments instead of javadoc style comments.

Use
/*
*
*/

Instead of
/**
*
*/