Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • All public / protected / package-private entities must have javadoc comments; remember this is the documentation for the entity's API.
  • private entities do not need to have javadoc comments, but if they do, the comments should be properly formatted and complete.
  • Acronyms in comments should be properly capitalized, e.g. YANG, NETCONF, SNMP.
  • Descriptions should avoid gratuitous capitalization and should avoid referencing class-names unless part of a @link pragma.

  • Class Descriptions
    • Descriptions of interfaces / classes / enums should start with a noun, and describe what the entity embodies.
    • For example "Representation of...", "Aggregation of...".
    • Avoid starting with "This class....", or "This interface..." etc. as it is obvious from the context, and the phrase is redundant.
    • Unit tests classes should also have a class description.
      • but methods within do not need to have javadoc comments, (although it is not discouraged)

  • Enum Constant Descriptions
    • Not only should the enum as a whole be documented, but each constant (which is also public) should be documented.
    • Typically a single line format is used, for example, for SortDirection.ASC you might have:
      • /** Designates ascending sort order. */

  • Constructor Descriptions
    • Descriptions of constructors should start with a passive verb, e.g. "Creates..." or "Constructs..."
    • Avoid starting the description with "This constructor..." or "Constructor", or "Default constructor"
    • The first sentence of the description should be a complete, high level summary of what is constructed.
    • Note that the first sentence of the constructor (or method) description is used in the generated "Method Summary" section of the documentation page; (see example below)
    • Any additional sentences should provide the reader with further detail as needed.
    • The description text should be written as prose, and therefore be capitalized and punctuated properly.
    • The direct use of type names or variable names should be avoided where possible; for example:
      • rather than "Constructs a StructureHolder for the given WidgetElement."
      • it would be better to write "Constructs a structure holder for the given widget element."

  • Method Descriptions
    • Descriptions of methods should start with a passive verb, e.g. "Returns...", "Adds...", "Computes..."
    • Avoid starting the description with "This method..."
    • Further sentences should provide additional details (in prose) as needed, typically referring to the method parameters and the return value (if any).
    • The description should include details of special circumstances, for example, if and when null might be returned instead of a value type.
    • Note that parameter / return types should not be referenced with @link pragmas in the method description; the javadoc compiler will automatically provide hyperlinks to those entities in the constructed documentation page (see example below).
  • Parameters and Return Value Descriptions
    • There should be a blank line between the method description and the first @param clause.
    • There should be @param clause for each parameter to the method.
    • There should be a @return clause if the method is declared as returning anything other than void.
    • As a general guide, the reader should get a good sense of what the method does and what the parameters are, from reading just the method description alone.
    • The description of the parameter / return value should simply remind the reader what the parameter / value is; the details of which they have already read in the method description.
    • The description (sentence fragment) should start with lower case and not end with a period (.); for example:
      • @param id the entity identifier
      • @return the corresponding entity; or null if no such entity exists
      • @return true, if the key exists; false otherwise

  • Thrown Exception Descriptions
    • Documentation should always be provided (with a @throws clause) for each type of exception thrown by the method (both checked and unchecked exceptions).
    • Remember, only checked exceptions should be part of the method signature; unchecked exceptions should be omitted.
    • For example:
      • @throws IllegalArgumentException if the provided value is out of bounds
      • @throws IllegalStateException if the context has not been initialized

  • Javadoc comments are parsed as HTML
    • Whitespace is ignored, so use <p> (but not <p></p> or <p/>) to mark paragraph breaks.
    • <pre> ... </pre> can be used for blocks of monospaced text (e.g. example code fragments).
    • <ul> <li> ... </li>... </ul> constructs can be used for bulleted lists.

...