Overview
The goal of this document is to formalize conventions and best practices around javadocs in the CDAP code base. It is assumed that readers know how to write syntactically valid javadocs.
The purpose of javadoc is to explain the intended meaning or purpose of the element it's attached to. It serves as a specification for that element's behavior. This specification is what then gets fulfilled by implementation code, and verified by tests.
Without this documentation, your code is incomplete. A reader might be able to puzzle out what the code is doing, but is left in the dark as to what the code intends to do, or what it promises to continue doing in the future. The reader can't make informed decisions about how they should interact with your code.
Content
The most important part of a javadoc is the content.
Requirements
In general, every class and public method in an api or spi module must have javadocs. Exceptions to this rule are getter methods that simply return the value of a private variable and methods that override another method.
Format
Format is not as important as content, but it is desirable to have a consistent standard across the project so that people know what to expect. Elements of a javadoc should be present in the following order:
/** * Summary fragment. * * Additional descriptive text. * * @param * @return * @throws * @deprecated */
There should be a new line before the at-clauses.
Summary Fragment
The summary fragment is a required description of what the class or method does. It is a fragment, meaning it is not a complete sentence. The first word should be capitalized and the fragment should end with a period.
Classes
Anything that can be instantiated should be described as a noun. For example:
A service that manages the lifecycle of programs.
and not:
Manages the lifecycle of programs.
Methods
Methods should be described as a verb. In other words, treat is like there is an implicit 'This method ...' in front of the summary fragment. For example:
Validates the specified program options and starts the program if they are valid.
Additional Descriptive Text
A summary fragment is often not enough for a reader to understand the full behavior of the API. Any additional details after the fragment should be in complete, grammatically correct sentences.
It is a good place to put clarifying examples, notes about performance, warnings about misusing the API, and any other information that might not fall under common usage patterns.
If a method modifies state, the additional descriptive text should mention what state is modified.
If the method throws exceptions,
At-clauses
Every at-clause should be followed by a fragment as a description. By convention, the fragment should not be capitalized and should not be a complete sentence. If the fragment is all that is needed, it should not contain a period at the end. For example:
@param limit the maximum number of results to return
If the fragment is not enough to sufficiently document the at-clause, everything after the first fragment should be a complete, grammatically correct sentence. Normal punctuation and capitalization should apply. For example:
@param limit the maximum number of results to return. If the limit is equal to or less than 0, no limit will be applied.
Notice that the second sentence is a complete sentence and not a fragment. The first word 'If' is captialized, and it ends with a period.
@param
Every method argument should be documented with its own @param clause. Multiple @param clauses should appear in same order that they appear in the method signature. If some instances or values for that parameter are not valid input, they must be documented. Similarly, if the parameter can be null, the behavior for a null value must be documented. For example:
@param limit the maximum number of results to return
is not a good javadoc because it does not address what happens if the limit is 0 or below. Does the method throw an exception? Does it do something else? A better javadoc would be:
@param limit the maximum number of results to return. If the limit is equal to or less than 0, no limit will be applied.
Parameters should be described as nouns and not verbs. In the examples above, 'limit' is correctly treated as a noun.
@param limit limits the size of the results
This incorrectly treats 'limit' as a verb.
@return
@throws
@deprecated
Guidelines
This section contains guidelines for writing javadocs for common CDAP constructs.