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.
Instantiable Types
Methods
Additional Descriptive Text
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.