Classes and Interfaces
Class-level doc comments should separate classes and interfaces into groups based on their package. Apply the following tags in this order within a class-level doc comment:
| Tag | Description |
|---|---|
@description | One or more lines describing the class or interface |
@see | References a relevant class or external resource |
@group | Documents the package the class belongs to |
@deprecated | Documents that the class should no longer be used |
Below is an example of a class-level doc comment:
/**
* @description Flightless bird endemic to the island of Mauritius.
* @see birds.RodriguesSolitaire
* @group birds
* @deprecated As of 1662; use {@link birds.NicobarPigeon} instead
*/
public class Dodo
@description
The @description tag should be followed by the description of the class. It should explain what a class is, as they represent an object rather than a function. Include information indeducible from the class name; for example, the description of the class SessionToken might be A unique identifier of an interaction session. Avoid starting class descriptions with This class is....
Class descriptions should follow the same principles behind method descriptions: brevity, correct spelling and grammar, neat wrapping, and describing the class in isolation.
@see
Read the @see tag section for methods.
Where the described class and referenced class share the same package, simply state the class name in the reference.
@group
Pair each @group tag with the name of whichever Seven20 package the class belongs to; e.g. Utilities.
@deprecated
Read the @deprecated tag section for methods.