@cparra/apexdocs 3.0.0-alpha.9 → 3.0.0-rc.0

package/README.md

@@ -1,197 +1,350 @@
 # ApexDocs
 
-<p align="center">
-  <b>ApexDocs is a Node.js library with CLI capabilities to docGenerator documentation for Salesforce Apex classes.</b>
-</p>
+<div align="center">
+  <b>CLI and Node library to generate documentation for Salesforce Apex classes.</b>
 
+[![CI](https://github.com/cesarParra/apexdocs/actions/workflows/ci.yaml/badge.svg)](https://github.com/cesarParra/apexdocs/actions/workflows/ci.yaml)
 [![License](https://img.shields.io/github/license/cesarParra/apexdocs)](https://github.com/cesarParra/apexdocs/blob/master/LICENSE)
+[![npm](https://img.shields.io/npm/dm/@cparra/apexdocs)](https://www.npmjs.com/package/@cparra/apexdocs)
+</div>
 
-## Description
+ApexDocs is a non-opinionated documentation generator for Salesforce Apex classes.
+It can output documentation in Markdown
+format,
+which allows you to use the Static Site Generator of your choice to create a documentation site that fits your needs,
+hosted in any static web hosting service.
 
-ApexDocs was originally built as an alternative to
-the [Java based ApexDoc tool](https://github.com/SalesforceFoundation/ApexDoc) originally created by Aslam Bari and
-later maintained by Salesforce.org, as that tool is no longer being maintained.
+## 💿 Installation
 
-ApexDocs is a Node.js library built on Typescript and hosted on [npm](https://www.npmjs.com/package/@cparra/apexdocs).
-It offers CLI capabilities to automatically document your source code, based on the ApexDoc style of documentation.
-Additionally, it can be imported and consumed directly by your JavaScript code.
-
-There are some key differences between ApexDocs and the Java based ApexDoc tool:
+```bash
+npm i -g @cparra/apexdocs
+```
 
-- **Recursive file search through your module directory structure**. In an `sfdx` based project, all of your classes
-  will be documented by specifying the top-most directory where file search should begin.
-- **Unopinionated documentation site generation**. Instead of creating HTML files, ApexDocs generates a Markdown (.md)
-  file per Apex class being documented. This means you can host your files in static web hosting services that parse
-  Markdown like Github Pages or Netlify, and use site generators like Jekyll or Gatsby. This gives you the freedom to
-  decide how to style your site to match your needs.
+## ⚡ Quick Start
 
-#### Features
+### CLI
 
-* Custom Annotations
+#### Markdown
 
-Any custom annotation defined in the Apexdoc is at the class level are supported, for example the following will be
-  output to the resulting markdown file:
+Run the following command to generate markdown files for your global Salesforce Apex classes:
 
-```apex
-/**
- * @MyCustomAnnotation This is a custom annotation
- */
-public class MyClass {
-}
+```bash
+apexdocs markdown -s force-app
 ```
 
-* Single Line ApexDoc Blocks
+#### OpenApi
 
-📒 Note: If you wish to have multiple `@` tags in a single line but don't want them to be treated as ApexDoc annotations, you can
-escape them by adding wrapping the annotation in ticks, for example
+Run the following command to generate an OpenApi REST specification for your Salesforce Apex classes
+annotated with `@RestResource`:
 
-```apex
-/**
- * @MyCustomAnnotation This is a custom annotation with an `@embedded` annotation
- */
+```bash
+apexdocs openapi -s force-app
 ```
 
+## 🚀 Features
+
+* Generate documentation for Salesforce Apex classes as Markdown files
+* Generate an OpenApi REST specification based on `@RestResource` classes
 * Support for grouping blocks of related code within a class
-* Support for HTML tags
-* OpenApi REST specification generation
 * Support for ignoring files and members from being documented
 * Namespace support
 * Configuration file support
+* Single line ApexDoc Blocks
+* Custom tag support
 * And much, much more!
 
-### Demo
+## 👀 Demo
+
+ApexDocs generates Markdown files, which can be integrated into any Static Site Generation engine,
+(e.g. Jekyll, Vitepress, Hugo, Docosaurus, etc.) to create a documentation site that fits your needs.
 
-ApexDocs currently supports generating markdown files for Jekyll and Docsify sites, as well as generating plain markdown
-files.
+This repo contains several example implementations in the `examples` directory, showcasing how to integrate
+with some of these tools.
+
+* [Examples](./examples)
 
 ### In the wild
 
-- [Expression](https://cesarparra.github.io/expression/)
+Here are some live projects using ApexDocs:
+
+- [Trailhead Apex Recipes](https://github.com/trailheadapps/apex-recipes)
+- [Salesforce Commerce Apex Reference](https://developer.salesforce.com/docs/commerce/salesforce-commerce/references/comm-apex-reference/cart-reference.html)
+- [Expression (API)](https://cesarparra.github.io/expression/)
 - [Nimble AMS Docs](https://nimbleuser.github.io/nams-api-docs/#/api-reference/)
-- [Yet Another Salesforce Logger](https://cesarparra.github.io/yet-another-salesforce-logger/#/)
 
-### [Docsify](https://docsify.js.org/)
+## ▶️ Available Commands
+
+`markdown`
+
+### Flags
+
+| Flag                          | Alias | Description                                                                                                                            | Default         | Required |
+|-------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------|
+| `--sourceDir`                 | `-s`  | The directory where the source files are located.                                                                                      | N/A             | Yes      |
+| `--targetDir`                 | `-t`  | The directory where the generated files will be placed.                                                                                | `docs`          | No       |
+| `--scope`                     | `-p`  | A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible.                    | `global`        | No       |
+| `--defaultGroupName`          | N/A   | The default group name to use when a group is not specified.                                                                           | `Miscellaneous` | No       |
+| `--namespace`                 | N/A   | The package namespace, if any. If provided, it will be added to the generated files.                                                   | N/A             | No       |
+| `--sortMembersAlphabetically` | N/A   | Sorts the members of a class, interface or enum alphabetically. If false, the members will be displayed in the same order as the code. | `false`         | No       |
+| `--includeMetadata `          | N/A   | Whether to include the file's meta.xml information: Whether it is active and and the API version                                       | `false`         | No       |
+| `--linkingStrategy`           | N/A   | The strategy to use when linking to other classes. Possible values are `relative`, `no-link`, and `none`                               | `relative`      | No       |
 
-Demo
+#### Linking Strategy
 
-- [Docsify](https://cesarparra.github.io/apexdocs/)
+The linking strategy determines how ApexDocs will link to other classes in your documentation. For example,
+if I have class `A` that links through class `B` (e.g. through an `{@link B}` tag, the `@see` tag,
+takes it as a param, returns it from a method, etc.), the linking strategy will determine how the link to class `B` is
+created.
 
-### [Jekyll](https://jekyllrb.com/)
+These are the possible values for the `linkingStrategy` flag:
 
-Demo
+- `relative`
 
-- [Jekyll](https://cesarparra.github.io/apexdocs-docsify-example/)
+Create a relative link to the class file.
+So if both classes are in the same directory, the link will be created as
+`[B](B.md)`.
+If the classes are in different directories, the link will be created as `[B](../path/to/B.md)`
 
-## Installation
+- `no-link`
+
+Does not create a link at all. The class name will be displayed as plain text.
+
+- `none`
+
+Does not apply any kind of logic. Instead, the links will be determined by the path to the file
+from the root of the documentation site OR by whatever path you have returned in the `transformReference` hook
+for the file.
+
+### Sample Usage
 
 ```bash
-npm i -g @cparra/apexdocs
+apexdocs markdown -s force-app -t docs -p global public namespaceaccessible -n MyNamespace
 ```
 
-## Usage
+`openapi`
 
-### CLI
+### Flags
+
+| Flag           | Alias | Description                                                                   | Default         | Required |
+|----------------|-------|-------------------------------------------------------------------------------|-----------------|----------|
+| `--sourceDir`  | `-s`  | The directory where the source files are located.                             | N/A             | Yes      |
+| `--targetDir`  | `-t`  | The directory where the generated files will be placed.                       | `docs`          | No       |
+| `--fileName`   | N/A   | The name of the OpenApi file.                                                 | `openapi.json`  | No       |
+| `--namespace`  | N/A   | The package namespace, if any. This will be added to the API file Server Url. | N/A             | No       |
+| `--title`      | N/A   | The title of the OpenApi file.                                                | `Apex REST API` | No       |
+| `--apiVersion` | N/A   | The version of the API.                                                       | `1.0.0`         | No       |
+
+### Sample Usage
 
 ```bash
-apexdocs-generate
-    -s src
-    -t docs
-    -p global
-    -g docsify
-```
-
-The CLI supports the following parameters:
-
-| Parameter                   | Alias | Description                                                                                                                                                                                                                                                                                                                                                                 | Default         | Required |
-|-----------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------|----------|
-| --sourceDir                 | -s    | The directory location which contains your apex .cls classes.                                                                                                                                                                                                                                                                                                               | N/A             | Yes      |
-| --targetDir                 | -t    | The directory location where documentation will be generated to.                                                                                                                                                                                                                                                                                                            | `docs`          | No       |
-| --recursive                 | -r    | Whether .cls classes will be searched for recursively in the directory provided.                                                                                                                                                                                                                                                                                            | `true`          | No       |
-| --scope                     | -p    | A list of scopes to document. Values should be separated by a space, e.g --scope public private. Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.                                                                                                                                   | `global`        | No       |
-| --targetGenerator           | -g    | Define the static file generator for which the documents will be created. Currently supports: `jekyll`, `docsify`, `plain-markdown`, and `openapi`.                                                                                                                                                                                                                         | `jekyll`        | No       |
-| --indexOnly                 | N/A   | Defines whether only the index file should be generated.                                                                                                                                                                                                                                                                                                                    | `false`         | No       |
-| --defaultGroupName          | N/A   | Defines the `@group` name to be used when a file does not specify it.                                                                                                                                                                                                                                                                                                       | `Miscellaneous` | No       |
-| --sanitizeHtml              | N/A   | When on, any special character within your ApexDocs is converted into its HTML code representation. This is specially useful when generic objects are described within the docs, e.g. "List< Foo>", "Map<Foo, Bar>" because otherwise the content within < and > would be treated as HTML tags and not shown in the output. Content in @example blocks are never sanitized. | true            | No       |
-| --openApiTitle              | N/A   | If using "openapi" as the target generator, this allows you to specify the OpenApi title value.                                                                                                                                                                                                                                                                             | `Apex REST Api` | No       |
-| --title                     | N/A   | Allows you to specify the home page main title. If using "openapi" this acts as an alias to the openApiTitle parameter                                                                                                                                                                                                                                                      | `Classes`       | No       |
-| --namespace                 | N/A   | The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. If generating an OpenApi definition, it will be added to the file's Server Url.                                                                                                                                                                | N/A             | No       |
-| --openApiFileName           | N/A   | If using "openapi" as the target generator, this allows you to specify the name of the output file.                                                                                                                                                                                                                                                                         | `openapi`       | No       |
-| --sortMembersAlphabetically | N/A   | Whether to sort the members of a class alphabetically.                                                                                                                                                                                                                                                                                                                      | `false`         | No       |
-| --includeMetadata           | N/A   | Whether to include the file's meta.xml information: Whether it is active and and the API version                                                                                                                                                                                                                                                                            | false           | No       |
-| --documentationRootDir      | N/A   | The root directory where the documentation will be generated. This is useful when you want to generate the documentation in a subdirectory of your project.                                                                                                                                                                                                                 | N/A             | No       |
-
-### Using a configuration file
-
-You can also use a configuration file to define the parameters that will be used when generating the documentation. Apexdocs
-uses [cosmiconfig](https://www.npmjs.com/package/cosmiconfig) to load the configuration file, which means it supports
-the following formats:
+apexdocs openapi -s force-app -t docs -n MyNamespace --title "My Custom OpenApi Title"
+```
+
+## 🔬 Defining a configuration file
+
+You can also use a configuration file to define the parameters that will be used when generating the documentation.
+
+Configuration files are the main way to integrate the generated documentation with the Static Site Generator of your
+choice and your build process, as well as configuring any custom behavior and the output of the generated files.
+
+### Overview
+
+Apexdocs uses [cosmiconfig](https://www.npmjs.com/package/cosmiconfig) to load the configuration file, which means it
+supports the following formats (plus anything else supported by cosmiconfig):
 
 - A `package.json` property, e.g. `{ "apexdocs": { "sourceDir": "src", "targetDir": "docs" } }`
 - A `.apexdocsrc` file, written in YAML or JSON, with optional extensions: `.yaml/.yml/.json/.js`
-- An `apexdocs.config.js` file that exports an object
+- An `apexdocs.config.js` (or `.mjs`) file that exports an object
 - A `apexdocs.config.ts` file that exports an object
 
-The configuration file should be placed in the root directory of your project.
-
-**Note that when using a configuration file, you can still override any of the parameters by passing them through the CLI.**
-
-When defining a `.js` or `.ts` configuration file, your object export can also contain the following functions that will
-allow you to override some of the default behavior:
-
-- `onBeforeFileWrite` - A function that will be called before a file is written to disk. It receives a `TargetFile` object
-  that contains the file's content, path, and name, etc. It should return a `TargetFile` object with the updated content.
-  The full object definition can be imported from `@cparra/apexdocs/lib/settings`
-- `onAfterProcess` - A function that will be called after all files have been processed. It receives a `TargetFile[]` array
-  with all of the files that were processed and does not return anything.
-- `frontMatterHeader` - A function that will be called before the front matter is written to the file (when using the Jekyll generator).
-  It receives a `TargetType` object
-  and should return a list of strings that will be written to the file as the front matter.
-  The full object definition can be imported from `@cparra/apexdocs/lib/settings`
-  and contains the following properties:
-  - `name` - The name of the type
-  - `typeName` - Can be 'class', 'interface', or 'enum'
-  -  `accessModifier` - The access modifier of the type
-  - `group` - The group to which the type belongs (if any)
-  - `description` - The description of the type as defined in the ApexDoc
+**The configuration file should be placed in the root directory of your project.**
+
+**Note that when using a configuration file, you can still override any of the parameters by passing them through the
+CLI.**
+
+### Configuration file
+
+When defining a configuration file, it is recommended to use ES modules syntax. The config file should `default`
+export an object with the parameters you want to use.:
+
+```javascript
+export default {
+  sourceDir: 'force-app',
+  targetDir: 'docs',
+  scope: ['global', 'public'],
+  ...
+}
+```
+
+Every property in the configuration file is optional, and if not provided, either the value provided through the
+CLI will be used, or the default value will be used.
+
+### Config Intellisense
+
+Using the `defineMarkdownConfig` helper will provide Typescript-powered intellisense
+for the configuration file options. This should work with both Javascript and Typescript files.
+
+```typescript
+import { defineMarkdownConfig } from "@cparra/apexdocs";
+
+export default defineMarkdownConfig({
+  sourceDir: 'force-app',
+  targetDir: 'docs',
+  scope: ['global', 'public'],
+  ...
+});
+```
+
+### Configuration Hooks
+
+When defining a `.js` or `.ts` configuration file, your object export can also make use
+of different hooks that will be called at different stages of the documentation generation process.
+
+All hooks can be async functions, allowing you to make asynchronous operations, like calling an external API.
+
+📒 Note: The extension hook functions are only available when generating Markdown files (not OpenApi).
+
+#### **transformReferenceGuide**
+
+Allows changing the Allows changing the frontmatter and content of the reference guide, or even if creating a reference
+guide page should be skipped.
+
+**Type**
+
+```typescript
+type TransformReferenceGuide = (referenceGuide: ReferenceGuidePageData) => Partial<ReferenceGuidePageData> | Skip | Promise<Partial<ReferenceGuidePageData> | Skip>;
+```
+
+Example: Updating the frontmatter
 
 ```typescript
-import {TargetFile} from "@cparra/apexdocs/lib/settings";
 export default {
-  onBeforeFileWrite: (file: TargetFile): TargetFile => {
-    console.log('onBefore writing', file);
-    return file;
-  },
-  onAfterProcess: (files: TargetFile[]) => {
-    console.log('onAfterProcess files', files);
-  },
+  transformReferenceGuide: (referenceGuide) => {
+    return {
+      // The frontmatter can either be an object, of the frontmatter string itself
+      frontmatter: { example: 'example' }
+    };
+  }
 };
+```
+
+Example: skipping the reference guide
 
+```typescript
+// The skip function is imported from the package
+import { defineMarkdownConfig, skip } from "@cparra/apexdocs";
+
+export default defineMarkdownConfig({
+  transformReferenceGuide: (referenceGuide) => {
+    return skip();
+  }
+});
 ```
 
-### Importing to your project
+#### **transformDocs**
+
+The main purpose of this hook is to allow you to skip the generation of specific pages,
+by returning a filtered array of `DocPageData` objects.
+
+If you want to modify the contents or frontmatter of the docs, use the `transformDocPage` hook instead.
+
+**Type**
+
+```typescript
+type TransformDocs = (docs: DocPageData[]) => DocPageData[] | Promise<DocPageData[]>
+```
+
+Example
+
+```typescript
+export default {
+  transformDocs: (docs) => {
+    return docs.filter(doc => doc.name !== 'MyClass');
+  }
+};
+```
+
+#### **transformDocPage**
+
+Allows changing the frontmatter and content of the doc page.
+
+**Type**
+
+```typescript
+type TransformDocPage = (
+  doc: DocPageData,
+) => Partial<ConfigurableDocPageData> | Promise<Partial<ConfigurableDocPageData>>
+```
+
+Example
+
+```typescript
+export default {
+  transformDocPage: (doc) => {
+    return {
+      frontmatter: { example: 'example' }
+    };
+  }
+};
+```
+
+#### **transformReference**
+
+Allows changing where the files are written to and how files are linked to each other.
+
+**Type**
+
+```typescript
+type TransformReference = (
+  reference: DocPageReference,
+) => Partial<ConfigurableDocPageReference> | Promise<ConfigurableDocPageReference>;
+```
+
+Example
+
+```typescript
+export default {
+  // Notice how we are setting the linking strategy to none, so that nothing is done
+  // to the links by the tool when it tries to link to other classes
+  linkingStrategy: 'none',
+  transformReference: (reference) => {
+    return {
+      // Link to the class in Github instead to its doc page.
+      referencePath: `https://github.com/MyOrg/MyRepo/blob/main/src/classes/${reference.name}.cls`
+    };
+  }
+};
+```
+
+## ⤵︎ Importing to your project
 
 If you are just interested in the Apex parsing capabilities, you can use the
 standalone [Apex Reflection Library](https://www.npmjs.com/package/@cparra/apex-reflection)
 which is what gets used by this library behind the scenes to generate the documentation files.
 
-## Documentation Format
+### 👨‍💻 Typescript
+
+If using Typescript, ApexDocs provides all necessary type definitions.
+
+## 📖 Documentation Guide
 
 ApexDocs picks up blocks of comments throughout your `.cls` files. The block must begin with `/**` and end with `*/`.
 
-### Documenting Classes and Interfaces
+### Top-level files (classes, interfaces, and enums)
 
-The following tags are supported at the class or interface level:
+The following tags are supported at the file level:
 
 **Note** Any custom generated tag is also supported. Custom tags can be added with at symbol (`@`) followed by the name
 of the tag. For example `@custom-tag`
 
-| Tag            | Description                              |
-|----------------|------------------------------------------|
-| `@description` | One or more lines describing the class.  |
-| `@see`         | The name of a related class.             |
-| `@group`       | The group to which the class belongs to. |
-| `@author`      | The author of the class.                 |
-| `@date`        | The date the class was created.          |
+| Tag            | Description                             |
+|----------------|-----------------------------------------|
+| `@description` | One or more lines describing the file.  |
+| `@see`         | The name of a related file.             |
+| `@group`       | The group to which the file belongs to. |
+| `@author`      | The author of the file.                 |
+| `@date`        | The date the file was created.          |
+| `@example`     | Example of how the code can be used.    |
 
 **Example**
 
@@ -203,30 +356,7 @@ public with sharing class TestClass {
 }
 ```
 
-### Documenting Enums
-
-The following tags are supported on the enum level:
-
-| Tag            | Description                                      |
-|----------------|--------------------------------------------------|
-| `@description` | One or more lines describing the enum.           |
-| `@see`         | The name of a related class, enum, or interface. |
-| `@group`       | The group to which the enum belongs to.          |
-| `@author`      | The author of the enum.                          |
-| `@date`        | The date the enum was created.                   |
-
-**Example**
-
-```apex
-/**
- * @description This is my enum description.
- */
-public Enum ExampleEnum {
-    VALUE_1, VALUE_2
-}
-```
-
-### Documenting Enum Values
+### Enum Values
 
 The following tags are supported on the enum value level:
 
@@ -245,9 +375,9 @@ public enum ExampleEnum {
 }
 ```
 
-### Documenting Properties
+### Properties and Fields
 
-The following tags are supported on the property level:
+The following tags are supported on the property and field level:
 
 | Tag            | Description                                |
 |----------------|--------------------------------------------|
@@ -262,7 +392,7 @@ The following tags are supported on the property level:
 public String ExampleProperty { get; set; }
 ```
 
-### Documenting Methods and Constructors
+### Methods and Constructors
 
 Methods and constructors support the same tags.
 
@@ -281,18 +411,43 @@ The following tags are supported on the method level:
 **Example**
 
 ```apex
-/**
- * @description This is my method description.
- * @param action The action to execute.
- * @return The result of the operation.
- * @example
- * Object result = SampleClass.call('exampleAction');
- */
-public static Object call(String action) {
-}
+   /**
+    * @description This is my method description.
+    * @param action The action to execute.
+    * @return The result of the operation.
+    * @example
+    * ```
+    * Object result = SampleClass.call('exampleAction');
+    * ```
+    public static Object call(String action) {
+    }
 ```
 
-### Using custom tags
+### Code Blocks
+
+Code blocks can be added to *almost any tag by using the triple backtick syntax. This is useful when you want to display
+code
+snippets with sample usage or examples.
+
+*The non-supported tags are the single line tags, like `@param`, `@return`, `@throws`, `@exception`, `@see`, etc*
+
+After the triple backticks, you can optionally specify the language of the code block. This defaults to `apex`,
+but it can be useful to override this when displaying code in other languages, such as `javascript` or `soql`.
+
+Example
+
+```apex
+   /**
+    * @description This is my method description.
+    * @sample-usage
+    * This is how you can use this method:
+    * ```
+    * Object result = SampleClass.call('exampleAction');
+    * ```
+    */
+```
+
+### Custom Tags
 
 You can use custom tags to document your code. Custom tags can be added with at symbol (`@`) followed by the name
 of the tag. Apexdocs will automatically format tags which words are separated by a dash (`-`) by separating them with a
@@ -311,8 +466,8 @@ display code snippets within your documentation.
     * System.debug('Hello World');
     * ```
     */
-   public class MyClass {
-   }
+public class MyClass {
+}
 ```
 
 Note that the language of the code block will be set to `apex` by default, but you can change it by adding the language
@@ -325,43 +480,11 @@ name after the triple backticks. For example, to display a JavaScript code block
     * console.log('Hello World');
     * ```
     */
-   public class MyClass {
-   }
-```
-
-### Grouping Declarations Within A Class
-
-A class might have members that should be grouped together. For example, you can have a class for constants with
-groups of constants that should be grouped together because they share a common behavior (e.g. different groups
-of constants representing the possible values for different picklists.)
-
-You can group things together within a class by using the following syntax:
-
-```apex
-// @start-group Group Name or Description
-public static final String CONSTANT_FOO = 'Foo';
-public static final String CONSTANT_BAR = 'Bar';
-// @end-group
+public class MyClass {
+}
 ```
 
-Groups of members are displayed together under their own subsection after its name or description.
-
-Some notes about grouping:
-
-* This is only supported on classes, NOT enums and interfaces
-* Supports
-    * Properties
-    * Fields (variables and constants)
-    * Constructors
-    * Methods
-* BUT only members of the same type are grouped together. For example,
-  if you have a group that contains properties and methods the properties will be grouped together under Properties ->
-  Group Name, and the methods will be grouped together under Methods -> Group Name
-* Does not support inner types (inner classes, interfaces, and enums)
-* It is necessary to use `// @end-group` whenever a group has been started, otherwise a parsing error will be raised for
-  that file.
-
-### Inline linking
+### Inline Linking
 
 Apexdocs allows you to reference other classes from anywhere in your docs, and automatically creates a link to that
 class file for easy navigation.
@@ -379,81 +502,63 @@ Apexdocs recognizes 2 different syntax when linking files:
  * @param param1 An <<ExampleClass>> instance. Can also do {@link ExampleClass}
  * @return The result of the operation.
  */
-public static Object doSomething(ExampleClass param1) {}
+public static Object doSomething(ExampleClass param1) {
+}
 ```
 
----
+#### Email linking
 
 Email addresses can also be inlined linked by using the `{@email EMAIL_ADDRESS}` syntax.
 
-### HTML support
+### Markdown formatting
 
-For the most part all HTML is sanitized when the `--sanitizeHtml` flag is passed a true value (which is the default).
-But there are some tags are allowed to have for the possibility of better
-styling long text.
+You can use Markdown syntax to format your documentation.
+For example, to create bold text, you can use `**bold text**`, and to create a list you can use the `*` character.
 
-- Allowed tags are: `br`, `p`, `ul`, `li`, and `code`
-
-Example
+**Example**
 
 ```apex
 /**
- * @description <p>This is a paragraph</p>
- * <p>And this is another paragraph</p>
- * <ul>
- *     <li>This is a list item</li>
- *     <li>This is another list item</li>
- * </ul>
+ * @description This is a description with **bold text**.
+ * Which contains a list:
+ * 
+ * **See Also**
+ * * [Title](https://example.com)
+ * * [Title 2](https://example.com)
  */
-class MyClass {
-}
 ```
 
-⚠️When the `--sanitizeHtml` flag is ON, any special character between code blocks (i.e. \```, \`, or `<code>`) will also
-be escaped.
-So if you have references to Apex generic collections (Set, List, or Maps) they will not look right, as the < and >
-symbols will be escaped.
-To prevent this you can turn the flag off, but be aware of the special considerations when doing this described below.
-
----
-
-For full control over the output you can also turn off the `--sanitizeHtml` flag, which will allow you
-to have any desired HTML within your docs.
-
-⚠️When the `--sanitizeHtml` flag is OFF, references to Apex generic collections (Set, List or Maps) can be problematic
-as they will be treated as an HTML tag and not displayed. For example if you have something
-like `@description Returns a List<String>`
-the `<String>` portion will be treated as HTML and thus not appear on the page.
-
-To fix this issue, when not sanitizing HTML, you should wrap any code that contain special characters that can be
-treated as HTML within '\`'
-or within `<code>` tags.
-
-### Displaying diagrams
-
-You can display diagrams in your documentation by leveraging Github's built-in [Mermaid](https://mermaid-js.github.io/mermaid/#/) support.
+### Grouping Declarations Within A Class
 
-If you are using a markdown generator that supports Mermaid (e.g. [Github's markdown](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/), 
-you can add diagrams to your documentation by using the
-`@mermaid` tag.
+A class might have members that should be grouped together. For example, you can have a class for constants with
+groups of constants that should be grouped together because they share a common behavior (e.g. different groups
+of constants representing the possible values for different picklists.)
 
-**Example**
+You can group things together within a class by using the following syntax:
 
 ```apex
-/**
- * @mermaid
- * graph TD
- *     A[Christmas] -->|Get money| B(Go shopping)
- *     B --> C{Let me think}
- *     C -->|One| D[Laptop]
- *     C -->|Two| E[iPhone]
- *     C -->|Three| F[Car]
- */
-public class MyClass {
-}
+// @start-group Group Name or Description
+public static final String CONSTANT_FOO = 'Foo';
+public static final String CONSTANT_BAR = 'Bar';
+// @end-group
 ```
 
-[Here's an example of how that looks](/docs/types/Classes/nspc.AnotherInterface.md)
+Groups of members are displayed together under their own subsection after its name or description.
+
+Some notes about grouping:
+
+* This is only supported on classes, NOT enums and interfaces
+* Supports
+    * Properties
+    * Fields (variables and constants)
+    * Constructors
+    * Methods
+* BUT only members of the same type are grouped together. For example,
+  if you have a group that contains properties and methods the properties will be grouped together under Properties ->
+  Group Name, and the methods will be grouped together under Methods -> Group Name
+* Does not support inner types (inner classes, interfaces, and enums)
+* It is necessary to use `// @end-group` whenever a group has been started, otherwise a parsing error will be raised for
+  that file.
 
 ### Ignoring files and members
 
@@ -466,39 +571,44 @@ Example
  /**
   * @ignore
   */
- public class MyClass {
-     public static void myMethod() {}
- }
+public class MyClass {
+    public static void myMethod() {
+    }
+}
  ```
 
-## Generating OpenApi REST Definitions
+## 📄 Generating OpenApi REST Definitions
 
 ApexDocs supports generating OpenApi 3.1.0 REST definitions based on any `@RestResource` classes in your source code.
 
 ### Usage
 
-To create an OpenApi specification file, run the `apexdocs-generate` and pass `openapi` to the `--targetGenerator` parameter.
-When using this generator, you can also pass a custom title through the `--openApiTitle` parameter. This title will be placed
-in the output file's `info.title` property, as defined by the [OpenApi documentation for the Info Object](https://spec.openapis.org/oas/v3.1.0#info-object)
-
+To create an OpenApi specification file, run `apexdocs openapi`
+When using this generator, you can also pass a custom title through the `--title` parameter.
+This title will be placed in the output file's `info.title` property,
+as defined by the [OpenApi documentation for the Info Object](https://spec.openapis.org/oas/v3.1.0#info-object)
 
 ```shell
-apexdocs-generate -s ./src -t docs -g openapi --openApiTitle "Custom OpenApi Title"
+apexdocs openapi -s ./src -t docs --title "Custom OpenApi Title"
 ```
 
 ### How It Works
 
-When generating an OpenApi document, since `@RestResource` classes need to be global in Apex, the `--scope` parameter will be ignored.
-Instead, ApexDocs will run through all classes annotated with `@RestResource` and add it to the output OpenApi file.
+When generating an OpenApi document,
+ApexDocs will run through all classes annotated with `@RestResource` and add it to the output OpenApi file.
 
-Once it finishes running, a file named `openapi.json` will be created in the specified `--targetDir`.
+Once it finishes running, a file named `openapi.json` (unless a different name is specified) will be created
+in the specified `--targetDir`.
 
 ### Configuring What Gets Created
 
 ApexDocs will automatically parse your source code and generate the OpenApi definition based on the HTTP related Apex
-annotations (RestResource, HttpDelete, HttpGet, HttpPatch, HttpPost, HttpGet). The different HTTP annotations will be used to generate a file that complies with the [OpenApi Specification v3.1.0](https://spec.openapis.org/oas/v3.1.0)
+annotations (`RestResource`, `HttpDelete`, `HttpGet`, `HttpPatch`, `HttpPost`, `HttpGet`). The different HTTP
+annotations will be used to generate a file that complies with
+the [OpenApi Specification v3.1.0](https://spec.openapis.org/oas/v3.1.0)
 
-Besides these annotations, the ApexDocs tool will also use any information provided through your code's Apexdocs, relying on
+Besides these annotations, the ApexDocs tool will also use any information provided through your code's Apexdocs,
+relying on
 some custom annotations that are specific to generating OpenApi definitions:
 
 * `@http-request-body`
@@ -517,6 +627,7 @@ The `schema` can either be a reference to another class in your source code (see
 or a fully defined custom schema (See the `Custom Schemas` section below).
 
 Example
+
 ```apex
 /**
  * @description This is a sample HTTP Post method
@@ -524,10 +635,10 @@ Example
  * description: This is an example of a request body
  * required: true
  * schema: ClassName
- */ 
+ */
 @HttpPost
 global static void doPost() {
-  ///...
+    ///...
 }
 ```
 
@@ -543,6 +654,7 @@ whether it is `required` or not, a `description`, and a `schema`.
 📝 Note that you can specify as many `@http-parameter` annotations as needed.
 
 Example
+
 ```apex
 /**
  * @description This is a sample HTTP Post method
@@ -566,11 +678,12 @@ global static String doPost() {
 ```
 
 📝 Note that each parameter of this annotation is expected to be on its own line. Parameters are treated as YAML,
-   so spacing is important.
+so spacing is important.
 
 #### @http-response
 
-Allows you to specify any HTTP response returned by your method. It supports receiving a `statusCode` with the response code,
+Allows you to specify any HTTP response returned by your method. It supports receiving a `statusCode` with the response
+code,
 a `description`, and a `schema`.
 
 If no `description` is provided then one will be automatically built using the `statusCode`.
@@ -599,50 +712,56 @@ global static String doPost() {
 #### Class References
 
 Whenever specifying a `schema` parameter, you can pass as a string the name of any class in your source code. This
-class will be parsed by the ApexDocs tool and automatically converted to a reference in the resulting OpenApi definition.
+class will be parsed by the ApexDocs tool and automatically converted to a reference in the resulting OpenApi
+definition.
 
-The tool will parse the class and create a reference that complies with [Apex's support for User-Defined Types](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_methods.htm#ApexRESTUserDefinedTypes)
+The tool will parse the class and create a reference that complies
+with [Apex's support for User-Defined Types](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_rest_methods.htm#ApexRESTUserDefinedTypes)
 
 ##### Reference Overrides
 
-When dealing with references, there might be cases when you want to manually tell the parser what type of object a property
+When dealing with references, there might be cases when you want to manually tell the parser what type of object a
+property
 or field is. For example, let's say we have a class that looks as follows
 
 ```apex
 public class MyClass {
-  public Object myObject;
-  public Account myAccountRecord;
+    public Object myObject;
+    public Account myAccountRecord;
 }
 ```
 
 In this case `myObject` has a type of `Object`, and `myAccountRecord` is an SObject. Neither of these will be accurately
-parsed when building the OpenApi definition, instead they will be simple be referenced as `object` without any properties.
+parsed when building the OpenApi definition, instead they will be simple be referenced as `object` without any
+properties.
 
-To accurately represent the shape of these objects, you can use the `@http-schema` annotation to essentially override its
-type during parsing. In this annotation you can specify the same thing you would in any `schema` property when dealing with any
+To accurately represent the shape of these objects, you can use the `@http-schema` annotation to essentially override
+its
+type during parsing. In this annotation you can specify the same thing you would in any `schema` property when dealing
+with any
 of the main `@http-*` methods, meaning a reference to another class, or a Custom Schema (as defined below).
 
 ```apex
 public class MyClass {
-  /**
-   * @description This is a generic reference to another class 
-   * @http-schema MyOtherClassName
-   */
-  public Object myObject;
-
-  /**
-   * @description This is a reference to an Account SObject
-   * @http-schema
-   * type: object
-   * properties:
-   *   Id:
-   *     type: string
-   *   Name:
-   *     type: string
-   *   CustomField__c:
-   *     type: number
-   */
-  public Account myAccountRecord;
+    /**
+     * @description This is a generic reference to another class 
+     * @http-schema MyOtherClassName
+     */
+    public Object myObject;
+
+    /**
+     * @description This is a reference to an Account SObject
+     * @http-schema
+     * type: object
+     * properties:
+     *   Id:
+     *     type: string
+     *   Name:
+     *     type: string
+     *   CustomField__c:
+     *     type: number
+     */
+    public Account myAccountRecord;
 }
 ```
 
@@ -652,7 +771,8 @@ If dealing with a collection, you can also specify the name of the reference eit
 
 📝 When using List or Set syntax in the `schema` of the ApexDoc `@http-*` annotation, only collections one level
 deep are supported (e.g. List<List<String>> is not supported). This is only a limitation when referencing collections
-on the ApexDoc `schema` property directly, and is fully supported when multi-level collections are inside of a referenced
+on the ApexDoc `schema` property directly, and is fully supported when multi-level collections are inside of a
+referenced
 class as part of your codebase.
 
 Maps are not supported, as it is not possible to know which keys the map will contain, and thus it is not possible
@@ -667,12 +787,13 @@ to convert that to a valid specification. For this use case, define a Custom Sch
  */
 @HttpPost
 global static void doPost() {
-  ///...
+    ///...
 }
 ```
 
 Inner class references are also supported, but note that you need to pass the full name of the reference,
-by using the `ParentClassName.InnerClassName` syntax, even if the inner class resides on the same class as the HTTP method
+by using the `ParentClassName.InnerClassName` syntax, even if the inner class resides on the same class as the HTTP
+method
 referencing it.
 
 ```apex
@@ -684,18 +805,20 @@ referencing it.
  */
 @HttpPost
 global static void doPost() {
-  ///...
+    ///...
 }
 ```
 
 #### Custom Schemas
 
 For any `schema` parameter in any of the HTTP ApexDocs annotations, besides specifying the name of a class, you
-can also specify a custom schema definition. The schema definition can either be for a primitive type, an `object` or an `array`
+can also specify a custom schema definition. The schema definition can either be for a primitive type, an `object` or an
+`array`
 
 **Primitives**
 
-For primitives, you should specify the `type` and an optional `format`, as defined by the [OpenApi Specification on Data Types](https://spec.openapis.org/oas/v3.1.0#data-types)
+For primitives, you should specify the `type` and an optional `format`, as defined by
+the [OpenApi Specification on Data Types](https://spec.openapis.org/oas/v3.1.0#data-types)
 
 ```apex
 /**
@@ -752,28 +875,22 @@ not reach into your org to get existing SObject describes. Because of this, when
 you should create a Custom Schema as defined above. This will also allow you to specify which specific
 fields are being received or returned.
 
-
 ### Considerations
 
 Please be aware of the following when using ApexDocs to create an OpenApi definition:
 
-* Map references are resolved as `object` with no properties, as it is not possible to know which keys the map will contain.
-When using maps either create a class that better represents the shape of the object and use a Class Reference, or
-define a Custom Schema in the `schema` section of the ApexDoc itself.
-* Same thing when referencing SObjects, as SObject describe parsing is not supported by the ApexDocs tool. When referencing
-SObjects, consider defining a Custom Schema in the `schema` section of the ApexDoc.
+* Map references are resolved as `object` with no properties, as it is not possible to know which keys the map will
+  contain.
+  When using maps either create a class that better represents the shape of the object and use a Class Reference, or
+  define a Custom Schema in the `schema` section of the ApexDoc itself.
+* Same thing when referencing SObjects, as SObject describe parsing is not supported by the ApexDocs tool. When
+  referencing
+  SObjects, consider defining a Custom Schema in the `schema` section of the ApexDoc.
 * ApexDoc is only able to parse through your source code, so references to other packages (namespaced classes) or any
-code that lives outside your source code is not supported. Consider creating a Custom Schema for those situations.
-* The return value and received parameters or your methods are currently not being considered when creating the OpenApi definition file.
-Instead, use the `@http-response` ApexDoc annotation to specify the return value, and `@http-parameter` to specify any
-expected parameter.
-
-## Typescript
-
-ApexDocs provides all necessary type definitions.
-
----
+  code that lives outside your source code is not supported. Consider creating a Custom Schema for those situations.
+* The return value and received parameters or your methods are currently not being considered when creating the OpenApi
+  definition file.
+  Instead, use the `@http-response` ApexDoc annotation to specify the return value, and `@http-parameter` to specify any
+  expected parameter.
 
-## 1.X
 
-Looking for documentation for version 1.X? Please refer to its [branch](https://github.com/cesarParra/apexdocs/tree/1.x)