Methods
Write ApexDocs method doc comments using only the tags in the table below. The tags are ordered by convention; they should appear in this order within doc comments:
| Tag | Description |
|---|---|
@description | One or more lines describing the method |
@param paramName | Description of a single parameter |
@return | Description of the return value of the method |
@throws ExceptionName | Description of an exception thrown by the method |
@see | References a related method |
@deprecated | Documents that the method should no longer be used |
Attach doc comments to all public and protected methods; simple private methods may not require them.
See the calculateAttackDamage() method for an example of a method doc comment:
/**
* @description Calculates damage applied to the enemy.
* @param baseDmg The base attack damage
* @param multiplier The attack multiplier
* @return The damage to be applied to the enemy
* @throws IllegalDamageException If the parameters are nonpositive
* @deprecated As of the June release; use computeDamage() instead
*/
public Integer calculateAttackDamage(Integer baseDmg, Decimal multiplier) {
// TODO: run calculations
}
@description
Attach the method's description to the @description tag. It should explain what a method does by beginning with a verb phrase, such as sets or gets. The verb phrase must be third-person declarative rather than second-person imperative; e.g. checks rather than check.
The method should be described in isolation - that is, without the broader context of its place within the product.
The following conventions for @description tags also apply to all other tags.
The description must be concise and without embellishment or unnecessary details. Avoid jargon or overly complex vocabulary.
Write doc comment descriptions in the present tense. Use correct spelling, capitalise the first word and end the sentence or phrase with a full stop (.). Correct grammar is preferred but may be sacrificed in favour of brevity.
The description should wrap neatly where it is too long for a single line; you should use your best judgement to decide when wrapping is necessary. Line-wrapped descriptions should be indented four spaces.
@param
For each @param tag, include the parameter name and a brief description of the parameter. Each parameter description must begin on the same column of its respective line (see the above example). By convention, the first non-article word is the type of the parameter (e.g. String), unless the type is one of the primitive Integer and Decimal types.
When describing parameters for simple methods, you may find that you are repeating elements of the method description; this is acceptable, as readers will often scan the doc comment for an explicit parameter description instead of reading the method description.
@return
Pair each @return tag with a description of the returned variable, beginning on the same column as any present parameter descriptions. Multiple @return tags may be required where there are different conditions for returning a variable; explain these conditions in the description.
Descriptions attached to @return tags should follow the same principles as those attached to @param tags.
Where the return type is void, omit the @return tag.
@throws
Pair each @throws tag with the name of the exception. Explain the condition causing the exception to be thrown.
@see
Follow each @see tag with a reference to another method closely related to the documented method. Format each reference as package.Class#method(Type, Type, …). The reference will appear as a link in the API documentation, enabling quick navigation to the referenced page.
Where the described method and referenced method share only the same package, or additionally the same class, format the reference as Class#method(Type, Type, …) or #method(Type, Type, …) respectively.
To link to an external resource instead, provide its URL using HTML markup; e.g. @see <a href="URL#value">label</a>.
Where a method doc comment has multiple @see tags, order them conventionally; see the article How to Write Doc Comments for the Javadoc Tool.
@deprecated
The @deprecated tag should be followed by the release the method was deprecated under (e.g. June 2024). Refer to which method should be used instead using a @link tag, formatted as {@link package.Class#method(Type, Type, …)}. Optionally, explain why the method was deprecated.
Avoid using inline @link tags outside of the @see or @deprecated tags; they degrade readability due to their colour and underlining in API documentation and their length in source code doc comments.