Page History

• 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 a @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
  • Note that these descriptions are short and to the point. If more detail is required about when or why the exceptions might be thrown, include it in the method description text.
    
    
• 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.

For more information, see How to Write Doc Comments for the Javadoc Tool. 

 Other Comments