@cparra/apexdocs 2.23.0 → 2.25.0-alpha.0

package/.github/workflows/ci.yaml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: ["master", "develop"]
+  pull_request:
+    branches: ["main", "develop"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup node
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+          cache: "npm"
+      - run: npm ci
+      - run: npm run build --if-present
+      - run: npm test

package/README.md

@@ -111,14 +111,14 @@ The CLI supports the following parameters:
 | --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. | `Apex REST Api` | No       |
-| --openApiTitle              | N/A   | If using "openapi" as the target generator, this allows you to specify the OpenApi title value.                                                                                                                                                                                                                                                                             | true            | 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       |
+| --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
 
@@ -178,20 +178,20 @@ which is what gets used by this library behind the scenes to generate the docume
 
 ApexDocs picks up blocks of comments throughout your `.cls` files. The block must begin with `/**` and end with `*/`.
 
-### Documenting Classes
+### Documenting Classes and Interfaces
 
-The following tags are supported on the class level:
+The following tags are supported at the class or interface 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. Note that this only gets added if it is explicitly defined through the configuration class that it should.        |
-| `@date`        | The date the class was created. Note that this only gets added if it is explicitly defined through the configuration class that it should. |
+| 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.          |
 
 **Example**
 
@@ -207,9 +207,13 @@ public with sharing class TestClass {
 
 The following tags are supported on the enum level:
 
-| Tag            | Description                            |
-|----------------|----------------------------------------|
-| `@description` | One or more lines describing the enum. |
+| 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**
 
@@ -222,6 +226,25 @@ public Enum ExampleEnum {
 }
 ```
 
+### Documenting Enum Values
+
+The following tags are supported on the enum value level:
+
+| Tag            | Description                             |
+|----------------|-----------------------------------------|
+| `@description` | One or more lines describing the value. |
+
+**Example**
+
+```apex
+public enum ExampleEnum {
+    /** @description This is my enum value description. */
+    VALUE_1,
+    /** @description This is my other enum value description. */
+    VALUE_2
+}
+```
+
 ### Documenting Properties
 
 The following tags are supported on the property level:
@@ -253,6 +276,7 @@ The following tags are supported on the method level:
 | `@example`                   | Example of how the code can be used or called.    |
 | `@throws` _ExceptionName_    | Description of an exception thrown by the method. |
 | `@exception` _ExceptionName_ | Same as `@throws`. V2 only                        |
+| `@mermaid`                   | Diagrams in Mermaid format.                       |
 
 **Example**
 

package/examples/plain-markdown/.forceignore

@@ -0,0 +1,12 @@
+# List files or directories below to ignore them when running force:source:push, force:source:pull, and force:source:status
+# More information: https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_exclude_source.htm
+#
+
+package.xml
+
+# LWC configuration files
+**/jsconfig.json
+**/.eslintrc.json
+
+# LWC Jest
+**/__tests__/**

package/examples/plain-markdown/README.md

@@ -0,0 +1,301 @@
+# Template file
+
+# BaseClass Class
+`abstract`
+
+## Namespace
+ns
+
+## Fields
+### `sampleEnumFromBase`
+
+#### Type
+[ns.SampleEnum](../Sample-Enums/ns.SampleEnum.md)
+
+
+---
+
+# ParentInterface Interface
+
+## Namespace
+ns
+
+## Methods
+### `sampleParentMethod()`
+
+### Signature
+```apex
+public void sampleParentMethod()
+``` 
+
+### Returns
+**void**
+
+
+---
+
+# ReferencedEnum Enum
+
+## Namespace
+ns
+
+## Enum Values
+
+
+---
+
+# SampleClass Class
+`virtual`
+
+aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex 
+
+deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+
+**Group** SampleGroup
+
+## Namespace
+ns
+
+## Example
+```apex
+SampleClass sample = new SampleClass();
+sample.doSomething();
+```
+
+**Extends**
+[ns.BaseClass](../Miscellaneous/ns.BaseClass.md)
+
+**Implements**
+[ns.SampleInterface](../Miscellaneous/ns.SampleInterface.md), 
+[ns.ParentInterface](../Miscellaneous/ns.ParentInterface.md)
+
+## Fields
+### `name`
+
+This is a sample field.
+
+#### Type
+String
+
+---
+
+### `sampleEnumFromBase`
+
+*Inherited*
+
+#### Type
+[ns.SampleEnum](../Sample-Enums/ns.SampleEnum.md)
+
+## Constructors
+### `SampleClass()`
+
+This is a sample constructor.
+
+### Signature
+```apex
+public SampleClass()
+``` 
+
+---
+### `SampleClass(name)`
+
+### Signature
+```apex
+public SampleClass(String name)
+``` 
+
+### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| name | String |  |
+
+## Methods
+### `sayHello()`
+
+`DEPRECATED`
+
+This is a sample method.
+
+### Signature
+```apex
+public virtual String sayHello()
+``` 
+
+### Returns
+**String**
+
+A string value.
+
+### Example
+```apex
+SampleClass sample = new SampleClass();
+sample.doSomething();
+```
+
+
+---
+
+# SampleEnum Enum
+
+`NAMESPACEACCESSIBLE`
+
+This is a sample enum. This references [ns.ReferencedEnum](../Miscellaneous/ns.ReferencedEnum.md) . 
+
+This description has several lines
+
+**Some Custom** 
+
+**Group** Sample Enums
+
+**Author** John Doe
+
+**Date** 2022-01-01
+
+**See** [ns.ReferencedEnum](../Miscellaneous/ns.ReferencedEnum.md)
+
+## Namespace
+ns
+
+```mermaid
+graph TD
+ A[SampleEnum] -->|references| B[ReferencedEnum]
+ B -->|referenced by| A
+```
+
+## Enum Values
+### VALUE1
+This is value 1
+### VALUE2
+This is value 2
+### VALUE3
+This is value 3
+
+
+---
+
+# SampleException Class
+
+## Namespace
+ns
+
+**Extends**
+Exception
+
+
+---
+
+# SampleInterface Interface
+
+`NAMESPACEACCESSIBLE`
+
+This is a sample interface
+
+**Author** John Doe
+
+**Date** 2020-01-01
+
+**See** [ns.SampleEnum](../Sample-Enums/ns.SampleEnum.md)
+
+**See** [ns.ReferencedEnum](./ns.ReferencedEnum.md)
+
+## Namespace
+ns
+
+```mermaid
+graph TD
+   A[SampleInterface] -->|extends| B[ParentInterface]
+   B -->|extends| C[GrandParentInterface]
+   C -->|extends| D[GreatGrandParentInterface]
+```
+
+## Example
+```apex
+SampleInterface sampleInterface = new SampleInterface();
+sampleInterface.sampleMethod();
+```
+
+**Extends**
+[ns.ParentInterface](./ns.ParentInterface.md)
+
+## Methods
+### `sampleMethod()`
+
+`NAMESPACEACCESSIBLE`
+
+This is a sample method
+
+**Custom Tag** 
+
+**Another Custom Tag** 
+
+### Signature
+```apex
+public String sampleMethod()
+``` 
+
+### Returns
+**String**
+
+Some return value
+
+### Throws
+[ns.SampleException](./ns.SampleException.md): This is a sample exception
+
+AnotherSampleException: This is another sample exception
+
+```mermaid
+graph TD
+  A[SampleInterface] -->|extends| B[ParentInterface]
+  B -->|extends| C[GrandParentInterface]
+  C -->|extends| D[GreatGrandParentInterface]
+```
+
+### Example
+```apex
+SampleInterface sampleInterface = new SampleInterface();
+sampleInterface.sampleMethod();
+```
+
+---
+
+### `sampleMethodWithParams(param1, param2, theEnum)`
+
+`NAMESPACEACCESSIBLE`
+`DEPRECATED`
+
+This is a sample method with parameters 
+
+Sometimes it won't be possible to find a NonExistent link.
+
+### Signature
+```apex
+public SampleEnum sampleMethodWithParams(String param1, Integer param2, SampleEnum theEnum)
+``` 
+
+### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+| param1 | String | This is the first parameter |
+| param2 | Integer | This is the second parameter |
+| theEnum | [ns.SampleEnum](../Sample-Enums/ns.SampleEnum.md) | This is an enum parameter |
+
+### Returns
+**[ns.SampleEnum](../Sample-Enums/ns.SampleEnum.md)**
+
+Some return value
+
+---
+
+### `sampleParentMethod()`
+
+*Inherited*
+
+### Signature
+```apex
+public void sampleParentMethod()
+``` 
+
+### Returns
+**void**
+
+

package/examples/plain-markdown/config/project-scratch-def.json

@@ -0,0 +1,5 @@
+{
+  "orgName": "cesarparra company",
+  "edition": "Developer",
+  "features": []
+}

package/examples/plain-markdown/force-app/classes/BaseClass.cls

@@ -0,0 +1,3 @@
+public abstract class BaseClass {
+    public SampleEnum sampleEnumFromBase;
+}

package/examples/plain-markdown/force-app/classes/ParentInterface.cls

@@ -0,0 +1,3 @@
+public interface ParentInterface {
+    void sampleParentMethod();
+}

package/examples/plain-markdown/force-app/classes/ReferencedEnum.cls

@@ -0,0 +1,3 @@
+public enum ReferencedEnum {
+
+}

package/examples/plain-markdown/force-app/classes/SampleClass.cls

@@ -0,0 +1,35 @@
+/**
+ * @description aliquip ex sunt officia ullamco anim deserunt magna aliquip nisi eiusmod in sit officia veniam ex
+ *              deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet cupidatat.
+ * @group SampleGroup
+ * @example
+ * SampleClass sample = new SampleClass();
+ * sample.doSomething();
+ */
+public with sharing virtual class SampleClass extends BaseClass implements SampleInterface, ParentInterface {
+    /**
+     * @description This is a sample field.
+     */
+    private final String name;
+
+    /**
+     * @description This is a sample constructor.
+     */
+    public SampleClass() {}
+
+    public SampleClass(String name) {
+        this.name = name;
+    }
+
+    /**
+     * @description This is a sample method.
+     * @return A string value.
+     * @example
+     * SampleClass sample = new SampleClass();
+     * sample.doSomething();
+     */
+    @Deprecated
+    public virtual String sayHello() {
+        return 'Hello';
+    }
+}

package/examples/plain-markdown/force-app/classes/SampleEnum.cls

@@ -0,0 +1,30 @@
+/**
+ * @description This is a sample enum. This references {@link ReferencedEnum}.
+ *
+ * This description has several lines
+ * @group Sample Enums
+ * @author John Doe
+ * @date 2022-01-01
+ * @some-custom Test. I can also have a {@link ReferencedEnum} here.
+ *                    And it can be multiline.
+ * @see ReferencedEnum
+ * @mermaid
+ * graph TD
+ *  A[SampleEnum] -->|references| B[ReferencedEnum]
+ *  B -->|referenced by| A
+ */
+@NamespaceAccessible
+public enum SampleEnum {
+    /**
+     * @description This is value 1
+     */
+    VALUE1,
+    /**
+     * @description This is value 2
+     */
+    VALUE2,
+    /**
+     * @description This is value 3
+     */
+    VALUE3
+}

package/examples/plain-markdown/force-app/classes/SampleException.cls

@@ -0,0 +1 @@
+public class SampleException extends Exception {}

package/examples/plain-markdown/force-app/classes/SampleInterface.cls

@@ -0,0 +1,46 @@
+/**
+ * @description This is a sample interface
+ * @author John Doe
+ * @date 2020-01-01
+ * @see SampleEnum
+ * @see ReferencedEnum
+ * @mermaid
+ * graph TD
+ *    A[SampleInterface] -->|extends| B[ParentInterface]
+ *    B -->|extends| C[GrandParentInterface]
+ *    C -->|extends| D[GreatGrandParentInterface]
+ * @example
+ * SampleInterface sampleInterface = new SampleInterface();
+ * sampleInterface.sampleMethod();
+ */
+@NamespaceAccessible
+public interface SampleInterface extends ParentInterface {
+    /**
+     * @description This is a sample method
+     * @return Some return value
+     * @throws SampleException This is a sample exception
+     * @throws AnotherSampleException This is another sample exception
+     * @custom-tag This is a custom tag
+     * @another-custom-tag This is another custom tag
+     * @mermaid
+     * graph TD
+     *   A[SampleInterface] -->|extends| B[ParentInterface]
+     *   B -->|extends| C[GrandParentInterface]
+     *   C -->|extends| D[GreatGrandParentInterface]
+     * @example
+     * SampleInterface sampleInterface = new SampleInterface();
+     * sampleInterface.sampleMethod();
+     */
+    String sampleMethod();
+
+    /**
+     * @description This is a sample method with parameters
+     *              Sometimes it won't be possible to find a {@link NonExistent} link.
+     * @param param1 This is the first parameter
+     * @param param2 This is the second parameter
+     * @param theEnum This is an enum parameter
+     * @return Some return value
+     */
+    @Deprecated
+    SampleEnum sampleMethodWithParams(String param1, Integer param2, SampleEnum theEnum);
+}