Document Apex Constructs and Features

Classes

When you document an Apex class, provide a comprehensive overview of the class’s purpose, responsibilities, and key characteristics.

In the summary sentence, describe the class’s ‌overall purpose. After the summary sentence, explain the rationale for the class’s sharing model if it’s not obvious. For example, explain why the class uses without sharing for a specific privileged operation. We also recommend using tags such as @author, @version, @since, @see, and @group, which all provide valuable metadata.

Here’s an example ApexDoc comment for the DataAggregationService class.

1/**
2 * This service class handles critical data aggregation tasks.
3 * It operates using 'without sharing' to ensure access to all necessary
4 * records for calculation, irrespective of the running user's sharing rules.
5 * Care must be taken when calling methods from this class.
6 * @author Jane Doe
7 * @since 0.1.0
8 */
9public without sharing class DataAggregationService {
10    //...
11}

Interfaces

Apex interfaces define a contract for what other classes can do without specifying how they do it. Focus your ApexDoc comments on this contract. In the main description, document the interface’s overall purpose and the contract that it defines. Standard metadata tags such as @author, @version, @since, and @see are also applicable.

Document each method declaration in the interface as a standard method. Clearly explain the method’s expected behavior, parameters, and return values. This documentation sets expectations for any class that implements the interface.

For an example of an interface with an ApexDoc comment, see ApexDoc Examples.

Enums

Enums in Apex define an abstract data type with a finite set of named constant values. In the main description, document the enum’s purpose and the set of concepts that it represents. You can also use standard tags such as @author, @version, @since, and @see.

Clarify individual enum constants if their names aren’t self-explanatory. Either describe a constant’s definition in the enum type’s ApexDoc main description, or use standard block comments that directly precede the line for the constant.

Apex enums implicitly include methods such as values(), valueOf(String), name(), and ordinal(). These standard methods generally don’t require explicit documentation within each specific enum’s ApexDoc comment.

Here’s an example ApexDoc comment for the Season enum.

1/**
2 * Potential seasons of the year
3 */
4public enum Season {
5  WINTER,
6  SPRING,
7  SUMMER,
8  FALL
9}

Methods and Constructors

Method and constructor documentation is critical for understanding how to use an Apex class.

When you document method and constructor parameters, use the @param block tag. Each parameter must have a corresponding @param tag. In the parameter description, describe the parameter’s name, its purpose, and any expectations regarding its type or content. Descriptions can include statements such as ‌“Cannot be null” or “A valid 18-character ID”.

For methods that return values, use the @return block tag. In the description, specify what is returned, including conditions for null values or specific data structures. Descriptions can include statements such as “A List of Account sObjects matching the filter criteria; an empty list if no matches are found.”

Use the @throws block tag to list all significant checked and unchecked exceptions that the method can explicitly throw, along with the conditions causing them. This documentation is crucial for identifying gaps in error handling.

For examples of methods and constructors with ApexDoc comments, see ApexDoc Examples.

Properties and Variables

Document public or global properties and class member variables that form part of a class’s public API.

In the ApexDoc comment’s main description section, explain the property’s purpose, its data type if it’s unclear from the method declaration, and any important usage notes. For example, include whether the property is read-only after initialization, or its default value. Block tags such as @see, @since, and @deprecated can also be applicable.

Here’s an example ApexDoc comment for the public maxRetries variable.

1/**
2 * Stores the maximum number of retry attempts for an operation.
3 * Defaults to 3 if not explicitly set.
4 * @since 0.1.1
5 */
6public Integer maxRetries {
7  get {
8    return maxRetries ?? 3;
9  }
10  set { maxRetries = value; }
11}

Triggers

Apex triggers are event-driven pieces of code that execute in response to specific database operations. Apex trigger definitions provide significant context, so we strongly recommend that you delegate all business logic to a separate handler class or a trigger framework. Therefore, ApexDoc doesn’t have any trigger-specific comment specifications.

However, you can still include standard ApexDoc tags such as @since and @see. For example, here’s a ApexDoc comment for the Opportunity trigger.

1/**
2 * @since 1.3.2
3 */
4trigger OpportunityTrigger on Opportunity (
5  before insert,
6  after insert,
7  before update,
8  after update,
9  before delete,
10  after delete,
11  after undelete
12) {
13  new OpportunityTriggerHandler().run();
14}

Annotations

Apex annotations, such as @AuraEnabled and @Future, modify the way a class or method is used by the platform and other code. For an element that has an annotation, document the implications of that annotation for the element’s behavior or usage.

Refer to this table as you write ApexDoc comments for elements with Apex annotations.