IcApexDoc

An API documentation generator for Salesforce Apex types and triggers and custom SObjects and fields.

• Overview
• Features
• Syntax
• Installation
• Usage
• Validation
• Troubleshooting
• License
• Release Notes

Overview

IcApexDoc is a command-line tool for generation of HTML-based documentation from Salesforce source code and metadata, specifically Apex types and triggers and custom object and field metadata files. Apex type and trigger documentation is derived from declaration signatures and ApexDoc-based documentation comments.

ApexDoc is a simple markup language embedded within Apex documentation comments (/** ... */) and is very similar to comment-based documentation tools for other languages such as JavaDoc and JSDoc.

There are several other implementations of ApexDoc including:

• ApexDoc - the original implementation from Salesforce Foundation; doesn't seem to be maintained any longer
• SfApexDoc - A derivative of ApexDoc with support for additional tags and features; doesn't seem to be maintained any longer
• ApexDocs - A Node.js library and tool that further extends the available tags and markup features

Additionally, Salesforce has recently (as of late 2025) published a specification for ApexDoc that will become the standard. IcApexDoc provides full support for that specification via a strict mode option for its validation features.

IcApexDoc is based on Illuminated Cloud 2's ApexDoc parser and HTML generator used to support its ApexDoc authoring features. However, while Illuminated Cloud 2 is a commercial product, IcApexDoc is completely free to use and is planned for an eventual (hopefully soon) open source release.

Features

Documentation generated by IcApexDoc shows extensive details for all declarations found by the command-line usage including hyperlinking for declaration types in signatures, explicit references in ApexDoc markup, and even links to Salesforce's Web-based documentation for system Apex types and standard SObjects.

The resulting documentation includes a primary landing page called Overview (corresponding to the generated file index.html) that lists all Apex types and triggers and all custom SObjects found in the project source and metadata files. Additionally other tabs are generated for each type of declaration, i.e., Classes, Enums, Interfaces, Triggers, and SObjects, to facilitate more focused cross-sections of the project.

Clicking on a type, trigger, or SObject link navigates to the specific page for that declaration which includes more header-level details for the top-level declaration as well as a list of all visible contained members. Members are listed together in a summary view but are also included in more detail below, broken out by declaration type, i.e., Constructors, Fields, Properties, and Methods.

A Groups tab is added (corresponding to the generated file groups.html) for all @group ApexDoc tag values found in type or trigger declarations with descriptions for each group optionally derived from group content files and links to all members of each respective group.

Finally, an Index tab is added (corresponding to the generated file index-all.html) with all declarations partitioned by the first character of the unqualified declaration name to provide efficient access to the documentation for class constants, utility methods, SObject fields, etc., by simple name.

Documentation for each generated declaration is based on its unique signature, i.e., annotations, modifiers, type, name, parameters, and bidirectional inheritance relationships, as well as the user-defined documentation. For Apex declarations, the user-defined documentation is based on an ApexDoc documentation comment immediately preceding the declaration itself; for SObjects and their fields, the user-defined documentation is based on the description and label elements found in the corresponding metadata XML files.

Syntax

ApexDoc comments are Apex block comments found immediately preceding any Apex top-level or body declaration that begin with /** (note two stars instead of just the one required to begin a normal block comment), e.g.:

/**
 * Common interface for two-dimensional closed shapes.
 */
public interface Shape {
    /**
     * Computes the shape perimeter.
     * 
     * @return the perimeter
     */
    Double getPerimeter();
}

ApexDoc comments can use the following to provide additional information and formatting:

• HTML markup - HTML markup can be used directly within ApexDoc comments. Note that this means that HTML escaping rules also apply to ApexDoc comments, e.g., use HTML entities as required. It is recommended that HTML markup in ApexDoc comments be kept simple to ensure that they render well in tools such as IDEs which may use simpler HTML rendering engines.
• Markdown - Unless strict mode is enabled, simple Markdown syntax can be used directly within ApexDoc comments and overview file contents. Hopefully in the near future Salesforce's ApexDoc specification will be amended to support Markdown-based formatting as that has become the de facto standard for technical documentation.
• ApexDoc tags - Like JavaDoc, JSDoc, etc., ApexDoc supports a number of tags of the form @tag [<params>] that specify information about the documented declaration.
• ApexDoc macros - ApexDoc also supports a number of simple macros to simplify declaration cross-referencing and even code/preformatted blocks.

Markdown support

Unless strict mode is enabled, IcApexDoc supports a subset of Markdown syntax for formatting of ApexDoc comments and overview file contents. The following Markdown features are supported:

• Bold - **text** or __text__
• Italic - *text* or _text_
• ~~Strikethrough~~ - ~~text~~
• Code - `code` or `` `codeWithBackticks` `` (also see Fenced code blocks below)
• ~~Composition~~ - The mechanisms above can be used in composition to style text as desired with the following limitations:
  • **bold**/*italic* and __bold__/_italic_ cannot be used in immediate composition with one another; use **bold**/_italic_ or __bold__/*italic* instead.
  • `code` must be the innermost applied style as it renders its contents exactly.
• Heading text - # (h1) to ###### (h6) followed by heading text, e.g.:

  # Heading 1
  ## Heading 2
  ### Heading 3
  #### Heading 4
  ##### Heading 5
  ###### Heading 6
  

• Block quotes

  > line1
  > line2
  > ...
  

• Fenced code blocks

  ```language
  line1
  line2
  ...
  ```
  

  • The language is optional. When provided, language-specific syntax highlighting is implemented using highlight.js, and a value of apex automatically acts as a synonym for java. I may contribute an Apex-specific grammar to that project so that the language is handled in a first-class manner with syntax highlighting of Apex-specific keywords, etc.
  • Additional balanced backticks can be used to allow rendering of fenced code blocks within a fenced code block, e.g.:

    ````markdown
    ```language
    line1
    line2
    ...
    ```
    ````
    

• Images - ![alt text](image.ext)
• Hyperlinks - [link text](url)
  • Hyperlinks can be references to Apex types and their members using the same reference syntax as in the {@link <reference>} and <<reference>> macros.
• Horizontal rules - --- (three or more dashes) on a separate line
• Tables

  | Header 1 | Header 2 | Header 3 |
  | -------- | -------- | -------- |
  | Data 1.1 | Data 1.2 | Data 1.3 |
  | Data 2.1 | Data 2.2 | Data 2.3 |
  

  • Table cell delimiters (|) can be included in table cells by escaping them (\|) or including them in code blocks (`A|B`).
  • Multi-line cell data can be provided by using HTML markup that results in multiple lines, e.g., <br/> or <p/> tags, raw HTML ordered/unordered lists, etc., all on the same line.
• Ordered lists

  1. list item 1
  2. list item 2
     with multiple lines
  3. list item 3
  

  The numbers used to begin items are unimportant, and 1. can be used pervasively to avoid having to renumber as items are inserted and removed. List items can span multiple lines, but continuation lines must be indented at least one space more than the line that begins the list item.
• Unordered lists

  * list item 1
  * list item 2
    with multiple lines
  * list item 3
  

  List items may begin with *, +, or -. List items can span multiple lines, but continuation lines must be indented at least one space more than the line that begins the list item.
• Ordered/unordered list nesting - List items indented relative to the immediate proceeding