Due to a ransomware attack, the wiki was reverted to a July 2022 version. . We apologize for the lack of a more recent valid backup.
...
- 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
@linkpragma. - 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)
- 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. */
- /** 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 @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
- @param id the entity identifier
- 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
- @throws IllegalArgumentException if the provided value is out of bounds
- 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.
...