v3.7.1

What's Changed

• Fixes issue when parsing a picklist custom field that has a single va… by @cesarParra in #222

Full Changelog: v3.7.0...v3.7.1

v3.7.0

What's Changed

• Changelog hook improvements by @cesarParra in #218

Full Changelog: v3.6.0...v3.7.0

v3.6.0

What's Changed

• Parse objects with inline fields by @cesarParra in #209

Custom field definitions in the object.meta.xml (metadata format as opposed to SFDX format where fields have their own XML file) are now included in the markdown documentation and changelog.

• Documenting extension fields by @cesarParra in #210

Standalone "extension" fields are now documented for both markdown and changelog commands. These are fields found in the source code without their parent object.meta-xml file. Usually these are fields that extend a Salesforce standard object or a custom object in another namespace not present in the source code.

• New members include their descriptions in the changelog, if present by @cesarParra in #212

Changelogs now include the description for new type members (class fields, properties, methods, etc. or custom fields) if present.

• Marking required fields when generating custom field documentation by @cesarParra in #213

Custom field documentation now includes if the field is required.

• Changelog frontmatter support by @cesarParra in #214

The changelog command now accepts a configuration hook from a config file (JS or TS): transformChangeLogPage. This hook allows you to provide a Frontmatter string or object to the generated changelog Markdown file.

• Upgrades to Apex Reflection version 2.16.0 by @cesarParra in #215

The library has been upgraded to the latest (2.16.0) version of the Apex Reflection library, providing better support for switch statements.

Full Changelog: v.3.5...v3.6.0

v3.5

What's Changed

• Fixing typo with CLI configuration name by @cesarParra in #202
• Fix error when parsing standard objects by @cesarParra in #204
• Custom object changelog by @cesarParra in #206
• Add support to parse picklist values by @RaviVaranasi in #207
• Changes to custom objects and fields now appear on the changelog. by @cesarParra in #208

New Contributors

• @RaviVaranasi made their first contribution in #207

Full Changelog: v3.4.0...v.3.5.0

v3.4.0

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

v3.3.0

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)

v3.2.0

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'],
  ...
});

v3.1.1

What's Changed

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

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

v3.1.0

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

v3.0.0 Release Candidate 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.