2. 📖 Documenting Apex code

ApexDocs picks up blocks of comments throughout your .cls files. The block must begin with /** and end with */.

Top-level files (classes, interfaces, and enums)

The following tags are supported at the file level:

Note Any custom generated tag is also supported. Custom tags can be added with at symbol (@) followed by the name of the tag. For example @custom-tag

Tag	Description
@description	One or more lines describing the file.
@see	The name of a related file.
@group	The group to which the file belongs to.
@author	The author of the file.
@date	The date the file was created.
@example	Example of how the code can be used.

Example

/**
 * @description This is my class description.
 */
public with sharing class TestClass {
}

Enum Values

The following tags are supported on the enum value level:

Tag	Description
@description	One or more lines describing the value.

Example

public enum ExampleEnum {
    /** @description This is my enum value description. */
    VALUE_1,
    /** @description This is my other enum value description. */
    VALUE_2
}

Properties and Fields

The following tags are supported on the property and field level:

Tag	Description
@description	One or more lines describing the property.

Example

/**
 * @description This is my property description.
 */
public String ExampleProperty { get; set; }

Methods and Constructors

Methods and constructors support the same tags.

The following tags are supported on the method level:

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.
@example	Example of how the code can be used or called.
@throws ExceptionName	Description of an exception thrown by the method.
@exception ExceptionName	Same as @throws. V2 only
@mermaid	Diagrams in Mermaid format.

Example

   /**
    * @description This is my method description.
    * @param action The action to execute.
    * @return The result of the operation.
    * @example
    * ```
    * Object result = SampleClass.call('exampleAction');
    * ```
    public static Object call(String action) {
    }

Code Blocks

Code blocks can be added to *almost any tag by using the triple backtick syntax. This is useful when you want to display code snippets with sample usage or examples.

The non-supported tags are the single line tags, like @param, @return, @throws, @exception, @see, etc

After the triple backticks, you can optionally specify the language of the code block. This defaults to apex, but it can be useful to override this when displaying code in other languages, such as javascript or soql.

Example

   /**
    * @description This is my method description.
    * @sample-usage
    * This is how you can use this method:
    * ```
    * Object result = SampleClass.call('exampleAction');
    * ```
    */

Custom Tags

You can use custom tags to document your code. Custom tags can be added with at symbol (@) followed by the name of the tag. Apexdocs will automatically format tags which words are separated by a dash (-) by separating them with a space and uppercasing them. For example, @custom-tag will be displayed as Custom Tag.

Within a custom tag, you can also add code blocks by using the triple backtick syntax. This is useful when you want to display code snippets within your documentation.

Example

   /**
    * @custom-tag This is a custom tag
    * @custom-tag-with-code
    * ```
    * System.debug('Hello World');
    * ```
    */
public class MyClass {
}

Note that the language of the code block will be set to apex by default, but you can change it by adding the language name after the triple backticks. For example, to display a JavaScript code block you can use:

   /**
    * @custom-tag-with-code
    * ```javascript
    * console.log('Hello World');
    * ```
    */
public class MyClass {
}

Inline Linking

Apexdocs allows you to reference other classes from anywhere in your docs, and automatically creates a link to that class file for easy navigation.

Apexdocs recognizes 2 different syntax when linking files:

• Javadoc's {@link FileName} syntax
• A class name wrapped in between << >>.

Example

/**
 * @description This is my method description. This method receives an <<ExampleClass>>.
 * @param param1 An <<ExampleClass>> instance. Can also do {@link ExampleClass}
 * @return The result of the operation.
 */
public static Object doSomething(ExampleClass param1) {
}

Email linking

Email addresses can also be inlined linked by using the {@email EMAIL_ADDRESS} syntax.

Markdown formatting

You can use Markdown syntax to format your documentation. For example, to create bold text, you can use **bold text**, and to create a list you can use the * character.

Example

/**
 * @description This is a description with **bold text**.
 * Which contains a list:
 * 
 * **See Also**
 * * [Title](https://example.com)
 * * [Title 2](https://example.com)
 */

Grouping Declarations Within A Class

A class might have members that should be grouped together. For example, you can have a class for constants with groups of constants that should be grouped together because they share a common behavior (e.g. different groups of constants representing the possible values for different picklists.)

You can group things together within a class by using the following syntax:

// @start-group Group Name or Description
public static final String CONSTANT_FOO = 'Foo';
public static final String CONSTANT_BAR = 'Bar';
// @end-group

Groups of members are displayed together under their own subsection after its name or description.

Some notes about grouping:

• This is only supported on classes, NOT enums and interfaces
• Supports
  • Properties
  • Fields (variables and constants)
  • Constructors
  • Methods
• BUT only members of the same type are grouped together. For example, if you have a group that contains properties and methods the properties will be grouped together under Properties -> Group Name, and the methods will be grouped together under Methods -> Group Name
• Does not support inner types (inner classes, interfaces, and enums)
• It is necessary to use // @end-group whenever a group has been started, otherwise a parsing error will be raised for that file.

Ignoring files and members

You can ignore files and members by using the @ignore tag on any ApexDoc block. If used at the class level, the entire file will be ignored. If used at the member level, only that member will be ignored.

Example

/**
 * @ignore
 */
public class MyClass {
   public static void myMethod() {
   }
}