The correct place for class-implementation documentation notes in Java

Question

Suppose I’m writing some complicated class in Java, and I want to document some things regarding the implementation of the class (i.e. things that shouldn’t interest the users of the class, but rather a programmer wishing to modify the actual implementation of the class).

Also, suppose those documentation notes I want to write are not specific to any single method/field but rather relevant to the entire implementation of the class. Where is the best place for such documentation notes?

Writing the notes just before the declaration of the class in the /** … **/ block will make them part of the main description of the class in the Javadoc HTML, which is bad - because I don’t want to bother the users of the class with that info.

score 1 · Accepted Answer · answered Mar 13 '16 at 08:32

You can always write the implementation notes as a non-javadoc comment block / header before your class declaration, typically:

package com.example;

import x.y.z.SomeClass;

/* non-javadoc (single asterisk)
Implementation notes:
  - something
  - something else
*/

/** javadoc (double asterisk)
 * Description for consumers of the class
 * @author someone
 */
public class MyClass {
  ...
}

This way, the implementation notes comment will be ignored by the javadoc tool and will only be visible in the source file.

The correct place for class-implementation documentation notes in Java

1 Answers1