Over the years, we’ve looked unsuccessfully for a tool to generate documentation for Salesforce Apex code. Something like Oracle’s Javadoc would have been ideal, but alas – that tool won’t parse Apex. The closest thing we’ve found is Aslam Bari’s ApexDoc. After trying that – as well as a few other obscure tools – we finally decided to bite the bullet and create something ourselves.
Enter SfApexDoc: a command-line tool that parses Apex comments and produces HTML documentation. We’ve been enhancing it off and on for the past several years, and are proud to offer it to the Salesforce community.
Documentation Format
SfApexDoc attempts to mimic the documentation format of Javadoc. A doc comment is written in HTML and must precede a class, interface, property, constructor, or method declaration. It is made up of two parts — 1. a description, and 2. block tags. The following tags are supported:
- @description (optional)
- @author
- @date
- @param name description (documentation)
- @return type (documentation)
- @see class or class.method
Rules:
- The first line contains the begin-comment delimiter (/**)
- The last line contains the end-comment delimiter (*/)
- Leading asterisks within the comment are optional
- The first line that begins with a ‘@’ ends the description. There is only 1 description per doc comment
- Add HTML tags for formatting (<b>, <i>, <p>, <br>, <code>, <pre> etc.)
/**
* Returns an Image object that can then be painted on the screen.
* The url argument must specify an absolute URL. The name
* argument is a specifier that is relative to the url argument.
* <p>
* This method always returns immediately, whether or not the
* that draw the image will incrementally paint on the screen.
* image exists. When this applet attempts to draw the image on
* the screen, the data will be loaded. The graphics primitives
*
* @param url - an absolute URL giving the base location of the image
* @param name - the location of the image, relative to the url argument
* @return the image at the specified URL
* @see Image
*/
public Image getImage(URL url, String name) {
try {
return getImage(new URL(url, name));
} catch (MalformedURLException e) {
return null;
}
}Comments can also be a single line:
/** available operations */
public enum OPERATION { ADD, SUBTRACT, MULTIPLY, DIVIDE }Usage
As mentioned above, SfApexDoc is a command-line tool with the following parameter options:
- -s (source folder): absolute or relative path to your Apex files. Typically, this will be the ‘classes’ folder in your Force.com project
- -x (file extension): optional; files with this extension will be processed. The default is ‘cls’
- -t (target folder): optional absolute or relative path where generated documentation files will be saved. If not specified, the current folder will be used
- -p (scope): optional; comma-separated list of scope names to document (e.g. protected, private). The default is global, public
- -h (home file): optional; absolute or relative path to your custom HTML home page. The file is parsed and displayed as your ‘Home’ page in the documentation
- -a (author file): optional; absolute or relative path to your custom author values. This text file should contain 2 lines: “projectName = My Project Name” and “author = My Name”
- -o (true | false): optional; boolean flag to specify whether properties and methods should be sorted alphabetically. Default is true
- -d: optional; output debug information
Files Filter
If you only want to generate documentation for a subset of your Apex classes, create a file called SfApexDocFiles.txt alongside your docAuthor.txt and docHome.txt files. Enter one filename per line, including the .cls or .trigger extension. When SfApexDoc is run, only those files listed in SfApexDocFiles.txt will be parsed.
Check the version number
java -jar SfApexDoc.jar -v[ersion]
Run from command line
java -jar SfApexDoc.jar -s <source_folder> [-t <target_folder>] [-h <homefile>] [-a <authorfile>] [-p <scope>] [-x <file extension>]
ANT target
<target name="SfApexDoc">
<java fork="true" classname="SfApexDoc" failonerror="true">
<classpath><path location="/Users/scox/Dev/Tools/SfApexDoc.jar"/></classpath>
<arg line="-s src/classes -a docAuthor.txt -h docHome.txt"/>
</java>
</target>VSCode Task
{ // generate SfApexDocs
"label": "SfApexDoc - generate",
"type": "shell",
"command": "cd ${workspaceFolder}/docs; java -jar $TOOLS/SfApexDoc.jar -s ../force-app/main/default/classes -p global -a docAuthor.txt -h docHome.txt -t .",
"problemMatcher": [],
"options": {
"env": {
"TOOLS": "/Users/steve/Dev/Tools"
}
},
}Release Notes
1.4.0 Ctors and HTML/CSS improvements (9/17/2022)
- created separate section for constructors
- ignore PMD annotations
- added page titles (browser title bar & tabs)
- updated links to Salesforce types
- fixed link-creation issue
- changed HTML structure from TABLEs to DIVs
1.3.0 Discontinued support for Eclipse plugin (11/22/2019)
- fixed “Exception parsing /**/ (empty comment)
- updated links to Salesforce primitive types
- correctly handle multiple properties declared on the same line
- added command line param to disable method and property sorting
- document private classes with no access specifier (properties and methods are not yet supported)
1.2.5 Allow specification of list of files to process (10/22/2014)
- fixed issue #30; bad source path causes plugin to fail silently
- if present, “SfApexDocFiles.txt” is parsed for a list of files to include. It is assumed that the file is in the working directory; file names include extension, but not directory information
1.2.4 Added support for webservice methods and @throws (3/21/2014)
- fixed links to nested classes; link is now to parent class, rather than non-existent page
- added support for @throws; properties and methods may specify one or more @throws tags
- added support for webservice methods; these methods will now be included in the docs whenver the “global” or “webservice” scope is specified
1.2.3 Single printable page and customizable CSS / images (3/1/2014)
- “all” page is now generated and displays all docs in a single, expanded page
- renamed the logo file; resource files no longer overwrite existing files. This means that you can modify your CSS and images and not worry about them getting overwritten by subsequent builds
1.2.2 CSS fixes and file selection dialog correctio (1/24/2014)
- cells in the documentaion table are now v-aligned to the top
- the browse buttons for the home and authhor pages were invoking a Save dialog, instead of an Open dialog
1.2.1 Non-doc comments and nested class handling (1/4/2014)
- better handling of non-doc comments (/* */)
- sort properties and methods of nested classes
- corrected usage message – scope params are comma-separated, not semi-colon-separated
1.2.0 Nested classes (12/16/2013)
- issue #3: nested classes
- moved all CSS from Java code to CSS file
1.1.1 Defect fixes, code cleanup (10/26/2013)
- added schedulable and batchable interfaces as links
- improved handling of tags
- added linking of subclasses
- issue 19: Eclipse plugin can only be run once
- issue 18: Eclipse plugin – remember preferences
1.1.0 Eclipse plugin, multi-line signatures (9/3/2013)
- removed unit testing code from SApexDoc.jar
- created Eclipse plugin
- fixed parsing of class, method, and property signatures spanning multiple lines
1.0.2 Better signature parsing, sorting (8/31/2013)
- instead of terminating on error, display file name, line index, line — and continue parsing
- fixed case sensitivity of “class” keyword; CLASS and Interface are now recognized
- methods and properties are sorted aphabetically
- added logs more unit tests
1.0.1 Links to types, unit tests, and GitLab project (8/25/2013)
- SfApexDoc is now on GitLab!
- added lots of unit tests
- created links in declaration lines and @see tabs for most Apex types and project custom types
- allow single-line comments
- @descrption tag is now optional
- added processing for interfaces
- added class/interface declaration subtitle line
1.0.0 Initial port from ApexDoc (8/23/2013)
- upgraded JRE to 1.6
- removed Eclipse plugin code
- command line ‘scope’ values are now delimited by “,” instead of “;”
- many improvements in parsing flexibility