ApexDox VS Code

ApexDox is A fast, reliable, and configurable documentation generator for Salesforce Apex .cls files, that works with both DX and non-DX projects. ApexDox uses a JSDoc-like inline comment syntax. Simply tell ApexDox where your class files are, and it will generate a set of static HTML pages that fully document each class/class file, including its properties, methods, enums, and annotations.

Features

• Run ApexDox and immediately launch your docs using the extension's built-in static server
• Supports documenting .cls files across multiple source directories for DX projects
• Includes easy-to-use commands and completion items for contextually auto-stubbing ApexDox comment blocks
• Customizable project "Home page", "project splash" section, and Class Group pages
• Links class, interface, method, prop, and enum signatures to source code hosted on GitHub
• Customize the favicon, and/or use your own logo, and other static assets in your docs
• Produces clean, readable HTML output (complements of pretty)
• Includes customized syntax highlighting to make your ApexDox comment blocks stand out and easy to read
• Generated documentation is fully searchable, powered by Lunr (supports wildcard searches using the * character and searching by page title using title:<search-term> syntax)
• Easily configurable using VS Code settings.json file or, for more safely checking configs into source control, using an .apexdoxrc (JSON) or apexdox.yml (YAML) file, depending on you and your team's preference (see examples in the sample app repo)

Table of Contents

• ApexDox Sample Documentation
• Commands
• Favicon & Logo Customization
• Extension Settings
  • The ${workspaceFolder} Variable
  • Documentation Engine Settings
  • Comment Block Settings
  • Examples
• Documenting Class Files
  • Documentation @ Tags
  • Special Tokens
  • Class Comments
  • Method Comments
  • Property and Inner Enum Comments
• Tips
• Known Issues
• History

ApexDox Sample Documentation

Check out our ApexDox sample docs to get a feel for what ApexDox documentation looks like: https://apexdox-sample-docs.surge.sh. The repository that these docs were created from lives here. If you'd like to easily test out different settings, install the extension and clone the repo; the settings are checked-in in the .vscode/settings.json file. Run ApexDox: Run from the command pallette, and ApexDox: Open Docs to generate new documentation and preview your changes locally.

Commands

You can launch the following commands via the command pallette (Ctrl/Cmd + Shift + P):

Create/Preview Docs

• ApexDox: Run: Run apexdox. Many aspects of how this command behaves can be configured using the settings below.
• ApexDox: Open Docs: Launch a server on localhost and open the generated documentation.

Auto-Stub Comment Blocks

Auto-stubbing comment blocks allows you to quickly document your class files with minimal effort. The appearance/style of comment stubs can be configured using the settings described in the next section. Auto-stub commands can be invoked in two ways:

• ApexDox: Stub Comment Block: Invoke this command on the line above a method, class/interface, property, or enum to stub an ApexDox comment based on the current context.
• /**: Same as ApexDox: Stub Comment Block, but as a Completion Item. Simply type /** and press Tab when prompted. See demos here and here.

Favicon & Logo Customization

To use your own favicon and logo (for the sidebar's 'Project Splash'), include files named logo.png and favicon.png in the apexdox.engine.assets array in .vscode/settings.json (or in the corresponding array of either .apexdoxrc or apexdox.yml). This will overwrite the existing files. You can read more about this and other ApexDox settings in the next section.

Extension Settings

The extension's settings can be configured using .vscode/settings.json, which optimally takes advantage of built-in VS Code intellisense. Alternatively, if you would like to check your config into source control, and minimize the risk of sharing unwanted VS Code settings across users, you can also use an .apexdoxrc (JSON) or apexdox.yml (YAML) file. If multiple configuration files happen to be present, the order of precedence is as follows:

1. apexdox.yml
2. .apexdoxrc
3. settings.json

The ${workspaceFolder} Variable

For any setting that refers to a path on your file system, you can use the variable ${workspaceFolder} to refer to the root folder of your project. If you have a multi-root setup, you can use ${workspaceFolder:directory-name} to indicate the correct directory.

To avoid confusion, please note that this is not a supported VS Code feature. VS Code does support this and other variables in other settings files, however, in this case, ApexDox VS Code handles the necessary replacements in settings.json, .apexdoxrc and in apexdox.yml to make checking config into source control and sharing across machines easier.

Documentation Engine Settings

Use these settings to configure the ApexDox documentation engine.

Comment Block Settings

Use these settings to configure the appearance of ApexDox comment block stubs (see the commands section for how to contextually stub a comment block).

Minimum Settings Example

This is all that's required to run apexdox. Technically, you could skip this too, and if your project is a standard DX or Salesforce project, the defaults should pick up your source files, but it's better to be explicit.

settings.json:

{
    "apexdox.engine.targetDirectory": "${workspaceFolder}\\documentation",
    "apexdox.engine.source": [{
        "path": "${workspaceFolder}\\src\\classes"
    }]
}

apexdox.yaml:

engine:
  targetDirectory: "${workspaceFolder}/documentation"
  source:
    - path: "${workspaceFolder}/src/classes"

.apexdoxrc:

{
  "engine": {
    "targetDirectory": "${workspaceFolder}/documentation",
    "source": [{
      "path": "${workspaceFolder}/src/classes"
    }]
  }
}

Expanded Settings Example

See our sample project for more complex configuration examples of all three config file flavors.

Documenting Class Files

ApexDox scans each class file, and looks for comment blocks with special tags (identified by @ similar to JS and JavaDoc), to find the documentation to include for a given class, interface, enum, method, or property. The comment blocks must always begin with /**, end with */, and can cover multiple lines (each subsequent line must begin with * or whitespace and then *). Here's an example of the most basic ApexDox comment block:

/**
 * @description This is the description!
 */

Documentation Tags

Note that in the table below, the 'Class' column includes any top-level types that live within a .cls file, including interfaces and enums. Tags are all optional and are located in the lines above the type's declaration.

Special Tokens

In addition to the @tags listed above, there are a few other special tokens to be aware of:

Class Comments (includes class-level Interfaces and Enums)

Located in the lines above any top-level type that lives within a .cls file, or in the lines above inner classes and interfaces.

Method Comments

In order for ApexDox to best identify class methods, the method line must contain an explicit access modifier / scope: global, public, private, testMethod, webService (some implicitly private methods can be detected, but be wary of this. See the note on implicit privacy in the Tips section below).

Property and Inner Enum Comments

These are the simplest comment blocks. They only support description tags (the tag itself may optionally be omitted for brevity). For properties to be detected by ApexDox, they must be given an explicit access modifier or have signatures beginning with the static keywork. Other implicitly private properties will not be detected.

Tips

• @description tags are optional; you may omit them. ApexDox comments without a tag will be interpreted as the type's description.
• All tags except @see, @group, and @group-name support comments over multiple lines.
• Important note on implicitly privacy: For ApexDox to best document your class files, it is generally best practice to always give your classes, methods, properties, interfaces, and emums explicit access modifiers. That said, ApexDox does have some ability to detect implicitly private types and methods. For instance, implicitly private @IsTest and inner classes, or methods whose signatures start with keywords like void, abstract, override and virtual, or with collections or primitive types can still be detected and will be assumed to be private (methods without access modifiers and whose signatures start with custom types or complex built-in types e.g. Messaging.SendEmailResult[] will not be detectable). However, in order to not confuse properties with local variables, properties must start with access modifiers or the static keyword in order to be detected. To best ensure accurate documentation, please always use access modifiers, which can only help to keep your code readable and easily understood!

Known Issues

ApexDox2 uses some modern HTML5 tags and JavaScript features, so unfortunately Internet Explorer is not supported (namely <summary> and <details> for easy, script-less collapsible menus and sections).

History

ApexDox VS Code is a complete TypeScript re-write of a Java project, originally maintained by Salesforce. After spending a considerable amount of time enhancing the Java project, originally intended for re-release as ApexDoc2 (a command line tool), I decided that given the current state of Apex/Salesforce development, abandoning that in favor of a VS Code extension made much more sense. That being said, TypeScript was the obvious choice. In addition to re-writing (and in many cases modifying, and hopefully improving!) all of the program's core logic, several major enhancements to the original have been made, including new features that take advantage of the VS Code eco-system.

I hope you enjoy the new and improved ApexDox VS Code!