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.