New Features

• Custom Object documentation support. The ApexDocs tool now generates documentation for custom objects and fields.

Important Updates

ApexDocs now leverages the https://github.com/forcedotcom/source-deploy-retrieve tool to locate Salesforce metadata (Apex classes, custom objects, and custom fields). This is the same tool that the sf CLI uses, which means that files will be located following the same rules (as defined here: https://github.com/forcedotcom/source-deploy-retrieve/blob/main/src/registry/metadataRegistry.json)

The major update this entails is that now the .forceignore file is respected. This can be turned off so I am open to providing a flag is anyone finds this behavior undesirable.

The other update is that now, to locate Apex classes (.cls files), they must be next to their corresponding cls-meta.xml file, whereas before it didn’t matter if the xml file did not exist. This should hopefully not make any difference as these are required in a Salesforce project anyways.

Known Limitations to be address in future releases

• Custom Objects are not yet supported by the OpenApi or Changelog command.
  • Note that the OpenApi format will probably not be supported ever by this tool, as Salesforce already has tools to produce OpenApi specifications out of SObjects.
• Salesforce supports specifying custom fields either within the object-meta.xml file (metadata format) or as a standalone file (field-meta.xml - SFDX format). This release only supports parsing standalone field-meta.xml fields.
• “Extension” fields are not yet supported. These are field-meta.xml fields that extend an object that is not in the source code (either a Standard object, or an object coming from a different package). This will be addressed in a future release.

Examples Updates

• The vitepress example was updated to show how to use hooks to generate different sidebars for Apex code or Custom Objects

What's Changed

• Upgrades to use the latest reflection library version
• A new flag was introduced for the changelog command that allows you to skip/not skip whether or not to create the changelog file if there are no changes
• When using a config file that specifies multiple configurations for different subcommands, a single subcommand can now be run when specified the subcommand name (previously you were prevented from doing this by the CLI and forced to run all commands configured)

New features

The changelog subcommand

This new subcommand generates a single Markdown file that lists any changes between 2 versions of your source code.

apexdocs changelog --previousVersionDir old-source-code --currentVersionDir force-app

Run multiple subcommands at the same time

You might want to generate different types of documentation using a single command. For example, if you are releasing a new version of your project, you might want to generate updated documentation Markdown files, and at the same time generate a changelog listing everything new.

You can do this by providing a configuration file that exports a configuration object which keys are the type of documentation you want to generate.

import { defineMarkdownConfig, defineChangelogConfig } from '@cparra/apexdocs';

export default {
  markdown: defineMarkdownConfig({
    sourceDir: 'force-app',
    targetDir: 'docs',
    scope: ['global', 'public'],
    ...
  }),
  changelog: defineChangelogConfig({
    previousVersionDir: 'force-app-previous',
    currentVersionDir: 'force-app',
    targetDir: 'docs',
    scope: ['global', 'public'],
  })
};

Then just run apexdocs without any additional subcommand to generate the documentation.

Exclude files through the config file

It is currently possible to exclude files from being included in the documentation by either using the scope flag or by adding an @ignore tag to the docs.

But there are situations where your source code is actually in scope, and at the same time you don't want to pollute the code with a bunch of @ignore comments for a specific external tool.

To allow for even further configuration around ignoring files, a new exclude property is configurable when using a package.json apexdocs config key, or a standalone config file.

This property allows you to specify a list of glob patterns that define the files you would like to be excluded from processing by the tool altogether.

import { defineMarkdownConfig } from "@cparra/apexdocs";

export default defineMarkdownConfig({
  ...
  exclude: ['**/MyClass.cls', '**/MyOtherClass.cls'],
  ...
});

What's Changed

• Fixing issue while reading multiple directories by @cesarParra in #180

Full Changelog: v3.1.0...v3.1.1

The main thing

Reduces the bundle size of the module by only distributing the contents of the dist directory.

What's Changed

• Doc updates by @cesarParra in #176
• Bump serve-static from 1.15.0 to 1.16.2 in /examples/docsify by @dependabot in #175
• Bump send and serve-static in /examples/docsify by @dependabot in #174
• Bump vite from 5.3.5 to 5.4.6 in /examples/vitepress by @dependabot in #177
• Only distributing the dist directory through the NPM package by @cesarParra in #178

Full Changelog: v2.25.0...v3.1.0

This marks the first Release Candidate for ApexDocs 3.0, with a large number of improvements and changes, both to the functionality and the code quality of the project.

New features

• The output markdown documentation now looks and contains the same content as the Salesforce documentation for Apex code
• New configuration hooks
• Enum values are now documented, and each specific value can receive its own documentation description.
• Code blocks are allowed through any tag (with a few documented exceptions) by wrapping your code in triple backticks (```).
• Objects referenced through @throws ,@exception , @return and, @param annotations now produce a link to the file (if they belong to the project)
• The Node package now exports a whole new set of functions and Typescript types, making it a lot more pleasant to import it as a module and work with the functionality, instead of through the CLI.

Improvements

• Improved examples folder in the repo
• Sanitizing HTML manually is no longer needed, it just works.
• General improvements to the way errors are presented when an exception happens when parsing the code or running a custom hook.

Deprecated

Specific Target Static Site Generators are no longer supported

In previous versions, it was possible to specify that the output should be in the format of Jekyll or Docsify, which are specific Static Site Generators (SSGs)

Since that was implemented, the industry has seen the rise of a huge number of other SSGs, with exciting new features and support for different component libraries.

This trend will probably continue, so we’ve made the decision that this tool should be as un-opinionated as possible on that matter.

The one thing that remains constant is that every single SSG continues to support Markdown as a first class citizen. So, the ability to target specific generators has been removed, and instead the ability to support plain markdown output has been vastly improved, including a way more powerful plugin engine that allows for consumers to easily integrate with the SSG of their choice.

Additionally, the examples folder now contains a lot of different examples on how to integrate with some popular SSGs (as of today), and the plan is to continue to grow this to continue to validate that the plugin framework is powerful enough to support anything thrown at it.

Breaking Changes

Changes to the CLI

• The apexdocs-generate command is now just apexdocs with subcommands for creating markdown files and OpenApi files
• Deprecated flags
  • recursive → With the SFDX format being now the de-facto standard, this is not necessary, as we can assume that this will always be true.
  • targetGenerator → See the Deprecated section as to why
  • indexOnly → This is a rare use case, so it was removed to clean up the API surface area. This can now be accomplished by using the provided hooks.
  • sanitizeHtml → This was added as patch-work to conditionally support special characters. 3.0 corrects any issues with special character rendering, so this is no longer needed
  • documentationRootDir → Can now be accomplished by using the hooks when integrating with a specific SSG.

Changes to how ApexDocs are parsed

• The @example and @mermaid tag now require you to use the triple backticks to document code blocks, instead of adding everything within them to a code block automatically.
• HTML is no longer supported. Markdown syntax should be used instead.

Bug fixes

• Previously, if you had sample code containing the @ symbol, this was treated as the start of a new custom tag. Now, everything within a code block is treated correctly until the code block is closed.
• Thefinal member modifier is now correctly surfaced in the documentation

Installation

Installation of this version can be done through this command:

npm i @cparra/[email protected]

Keep in mind that this is a major version change (we follow semantic versioning), so there are breaking changes if you are coming from a previous version of the tool.

ApexDocs 3.0.0

This is a new major release of ApexDocs, which means a lot of new features but also breaking changes.

New features

• The output markdown documentation now looks and contains the same content as the Salesforce documentation for Apex code
• New configuration hooks
• Enum values are now documented, and each specific value can receive its own documentation description.
• Code blocks are allowed through any tag (with a few documented exceptions) by wrapping your code in triple backticks (```).
• Objects referenced through @throws ,@exception , @return and, @param annotations now produce a link to the file (if they belong to the project)
• The Node package now exports a whole new set of functions and Typescript types, making it a lot pleasant to import it as a module and work with the functionality, instead of through the CLI.
• Besides using the CLI, the ApexDocs processing functionality can now be called imperatively from Javascript/Typescript by importing the process function.
• Tags can now be excluded from appearing in the documentation by using the excludeTags configuration property.

Improvements

• Improved examples folder in the repo
• Sanitizing HTML manually is no longer needed, it just works.
• General improvements to the way errors are presented when an exception happens when parsing the code or running a custom hook.

Deprecated

Specific Target Static Site Generators are no longer supported

In previous versions, it was possible to specify that the output should be in the format of Jekyll or Docsify, which are specific Static Site Generators (SSGs)

Since that was implemented, the industry has seen the rise of a huge number of other SSGs, with exciting new features and support for different component libraries.

This trend will probably continue, so we’ve made the decision that this tool should be as un-opinionated as possible on that matter.

The one thing that remains constant is that every single SSG continues to support Markdown as a first class citizen. So, the ability to target specific generators has been removed, and instead the ability to support plain markdown output has been vastly improved, including a way more powerful plugin engine that allows for consumers to easily integrate with the SSG of their choice.

Additionally, the examples folder now contains a lot of different examples on how to integrate with some popular SSGs (as of today), and the plan is to continue to grow this to continue to validate that the plugin framework is powerful enough to support anything thrown at it.

Breaking Changes

Changes to the CLI

• The apexdocs-generate command is now just apexdocs with subcommands for creating markdown files and OpenApi files
• Deprecated flags
  • recursive → With the SFDX format being now the de-facto standard, this is not necessary, as we can assume that this will always be true.
  • targetGenerator → See the Deprecated section as to why
  • indexOnly → This is a rare use case, so it was removed to clean up the API surface area. This can now be accomplished by using the provided hooks.
  • sanitizeHtml → This was added as patch-work to conditionally support special characters. 3.0 corrects any issues with special character rendering, so this is no longer needed
  • documentationRootDir → Can now be accomplished by using the hooks when integrating with a specific SSG.

Changes to how ApexDocs are parsed

• The @example and @mermaid tag now require you to use the triple backticks to document code blocks, instead of adding everything within them to a code block automatically.
• HTML is no longer supported. Markdown syntax should be used instead.

Bug fixes

• Previously, if you had sample code containing the @ symbol, this was treated as the start of a new custom tag. Now, everything within a code block is treated correctly until the code block is closed.
• Thefinal member modifier is now correctly surfaced in the documentation

Installation

Installation of this version can be done through this command:

npm i @cparra/apexdocs

Keep in mind that this is a major version change (we follow semantic versioning), so there are breaking changes if you are coming from a previous version of the tool.

What's Changed

• Bump braces from 3.0.2 to 3.0.3 by @dependabot in #124
• Bump ws from 7.5.7 to 7.5.10 by @dependabot in #130
• Bump fast-xml-parser from 4.2.5 to 4.4.1 by @dependabot in #151
• Updating to the latest Reflection package version by @cesarParra in #158

Full Changelog: v2.24.0...v2.25.0

What's Changed

• Fixing default reference in the CLI parameters table by @cesarParra in #117
• Apex reflection dependency upgrade by @cesarParra in #118

Full Changelog: v2.23.0...v2.24.0

What's Changed

• Introducing a new configuration function (frontMatterHeader) that allows for configuring the Jekyll front matter output by @cesarParra in #112

See this for all available configuration functions: https://github.com/cesarParra/apexdocs?tab=readme-ov-file#using-a-configuration-file

• Introducing a way to sort type members when generating documentation files by @cesarParra in #114

See the sortMembersAlphabetically configuration flag https://github.com/cesarParra/apexdocs?tab=readme-ov-file#cli

• Fixing issue where configuration file configs are not respected when argv is configured with a default by @cesarParra in #115

Full Changelog: v2.22.0...v2.23.0