@cparra/apexdocs 2.25.0-alpha.6 → 2.25.0-alpha.8

package/dist/cli/generate.js

@@ -166,66 +166,60 @@ var __spreadValues$f = (a, b) => {
 };
 var __spreadProps$f = (a, b) => __defProps$f(a, __getOwnPropDescs$f(b));
 function adaptDescribable(describable, linkGenerator) {
-  function describableToRenderableContent(describable2) {
-    if (!describable2) {
-      return;
-    }
-    let content = [];
-    for (let i = 0; i < describable2.length; i++) {
-      const line = describable2[i];
-      const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
-      if (codeBlockMatch) {
-        const language = codeBlockMatch[1] || "apex";
-        const codeBlockLines = [];
-        i++;
-        while (i < describable2.length) {
-          const currentLine = describable2[i];
-          if (currentLine.trim() === "```") {
-            break;
-          }
-          codeBlockLines.push(currentLine);
-          i++;
+  return {
+    description: describableToRenderableContent(describable, linkGenerator)
+  };
+}
+function describableToRenderableContent(describable, linkGenerator) {
+  if (!describable) {
+    return;
+  }
+  let content = [];
+  for (let i = 0; i < describable.length; i++) {
+    const line = describable[i];
+    const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
+    if (codeBlockMatch) {
+      const language = codeBlockMatch[1] || "apex";
+      const codeBlockLines = [];
+      i++;
+      while (i < describable.length) {
+        const currentLine = describable[i];
+        if (currentLine.trim() === "```") {
+          break;
         }
-        content = [
-          ...content,
-          {
-            __type: "code-block",
-            language,
-            content: codeBlockLines
-          },
-          { __type: "empty-line" }
-        ];
-        continue;
+        codeBlockLines.push(currentLine);
+        i++;
       }
       content = [
         ...content,
-        ...replaceInlineReferences(line, linkGenerator),
         {
-          __type: "empty-line"
-        }
+          __type: "code-block",
+          language,
+          content: codeBlockLines
+        },
+        { __type: "empty-line" }
       ];
+      continue;
     }
-    return content.filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1));
+    content = [
+      ...content,
+      ...replaceInlineReferences(line, linkGenerator),
+      {
+        __type: "empty-line"
+      }
+    ];
   }
-  return {
-    description: describableToRenderableContent(describable)
-  };
+  return content.filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1));
 }
 function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
   var _a, _b, _c;
   function extractCustomTags(type) {
     var _a2, _b2;
-    const baseTags = ["description", "group", "author", "date", "see", "example", "mermaid", "throws", "exception"];
+    const baseTags = ["description", "group", "author", "date", "see", "example", "throws", "exception"];
     return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase())).map((currentAnnotation) => __spreadProps$f(__spreadValues$f({}, adaptDescribable(currentAnnotation.bodyLines, linkGenerator)), {
       name: currentAnnotation.name
     }))) != null ? _b2 : [];
   }
-  function extractAnnotationBodyLines(type, annotationName) {
-    var _a2, _b2;
-    return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.find(
-      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName
-    )) == null ? void 0 : _b2.bodyLines;
-  }
   function extractAnnotationBody(type, annotationName) {
     var _a2, _b2;
     return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.find(
@@ -236,28 +230,13 @@ function adaptDocumentable(documentable, linkGenerator, subHeadingLevel) {
     var _a2, _b2;
     return (_b2 = (_a2 = type.docComment) == null ? void 0 : _a2.annotations.filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === "see").map((currentAnnotation) => currentAnnotation.body)) != null ? _b2 : [];
   }
-  function bodyLinesToCodeBlock(language, bodyLines) {
-    if (!bodyLines) {
-      return;
-    }
-    return {
-      __type: "code-block",
-      language,
-      content: bodyLines
-    };
-  }
   return __spreadProps$f(__spreadValues$f({}, adaptDescribable((_a = documentable.docComment) == null ? void 0 : _a.descriptionLines, linkGenerator)), {
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
     customTags: extractCustomTags(documentable),
-    mermaid: {
-      headingLevel: subHeadingLevel,
-      heading: "Diagram",
-      value: bodyLinesToCodeBlock("mermaid", extractAnnotationBodyLines(documentable, "mermaid"))
-    },
     example: {
       headingLevel: subHeadingLevel,
       heading: "Example",
-      value: bodyLinesToCodeBlock("apex", (_c = (_b = documentable.docComment) == null ? void 0 : _b.exampleAnnotation) == null ? void 0 : _c.bodyLines)
+      value: describableToRenderableContent((_c = (_b = documentable.docComment) == null ? void 0 : _b.exampleAnnotation) == null ? void 0 : _c.bodyLines, linkGenerator)
     },
     group: extractAnnotationBody(documentable, "group"),
     author: extractAnnotationBody(documentable, "author"),
@@ -973,7 +952,7 @@ const documentablePartialTemplate = `
 
 {{#if doc.example.value}}
 {{ heading doc.example.headingLevel doc.example.heading }}
-{{code doc.example.value}}
+{{{renderContent doc.example.value}}}
 {{/if}}
 `.trim();
 

package/examples/vitepress/docs/Miscellaneous/apexdocs.MultiInheritanceClass.md

@@ -72,7 +72,5 @@ public virtual String sayHello()
 A string value.
 
 ##### Example
-```apex
-SampleClass sample = new SampleClass();
-sample.doSomething();
-```
+SampleClass sample = new SampleClass(); 
+sample.doSomething();

package/examples/vitepress/docs/Miscellaneous/apexdocs.SampleInterface.md

@@ -8,6 +8,13 @@ title: SampleInterface
 
 This is a sample interface
 
+**Mermaid** 
+
+graph TD 
+A[SampleInterface] -->|extends| B[ParentInterface] 
+B -->|extends| C[GrandParentInterface] 
+C -->|extends| D[GreatGrandParentInterface]
+
 **Author** John Doe
 
 **Date** 2020-01-01
@@ -19,19 +26,9 @@ This is a sample interface
 ## Namespace
 apexdocs
 
-## Diagram
-```mermaid
-graph TD
-   A[SampleInterface] -->|extends| B[ParentInterface]
-   B -->|extends| C[GrandParentInterface]
-   C -->|extends| D[GreatGrandParentInterface]
-```
-
 ## Example
-```apex
-SampleInterface sampleInterface = new SampleInterface();
+SampleInterface sampleInterface = new SampleInterface(); 
 sampleInterface.sampleMethod();
-```
 
 **Extends**
 [apexdocs.ParentInterface](./apexdocs.ParentInterface.md)
@@ -51,6 +48,13 @@ This is a custom tag
 
 This is another custom tag
 
+**Mermaid** 
+
+graph TD 
+A[SampleInterface] -->|extends| B[ParentInterface] 
+B -->|extends| C[GrandParentInterface] 
+C -->|extends| D[GreatGrandParentInterface]
+
 #### Signature
 ```apex
 public String sampleMethod()
@@ -66,19 +70,9 @@ Some return value
 
 AnotherSampleException: This is another sample exception
 
-#### Diagram
-```mermaid
-graph TD
-  A[SampleInterface] -->|extends| B[ParentInterface]
-  B -->|extends| C[GrandParentInterface]
-  C -->|extends| D[GreatGrandParentInterface]
-```
-
 #### Example
-```apex
-SampleInterface sampleInterface = new SampleInterface();
+SampleInterface sampleInterface = new SampleInterface(); 
 sampleInterface.sampleMethod();
-```
 
 ---
 

package/examples/vitepress/docs/Miscellaneous/apexdocs.Url.md

@@ -5,9 +5,10 @@ title: Url
 # Url Class
 
 Represents a uniform resource locator (URL) and provides access to parts of the URL. 
-Enables access to the base URL used to access your Salesforce org. 
- 
-## Usage 
+Enables access to the base URL used to access your Salesforce org.
+
+**Usage** 
+
 Use the methods of the `System.URL` class to create links to objects in your organization. Such objects can be files, images, 
 logos, or records that you want to include in external emails, in activities, or in Chatter posts. For example, you can create 
 a link to a file uploaded as an attachment to a Chatter post by concatenating the Salesforce base URL with the file ID: 
@@ -31,8 +32,25 @@ Account acct = [SELECT Id FROM Account WHERE Name = 'Acme' LIMIT 1];
 String fullRecordURL = URL.getOrgDomainURL().toExternalForm() + '/' + acct.Id;
 ```
 
+**Version Behavior Changes** 
+
+In API version 41.0 and later, Apex URL objects are represented by the java.net.URI type, not the java.net.URL type. 
+ 
+The API version in which the URL object was instantiated determines the behavior of subsequent method calls to the 
+specific instance. Salesforce strongly encourages you to use API 41.0 and later versions for fully RFC-compliant URL 
+parsing that includes proper handling of edge cases of complex URL structures. API 41.0 and later versions also enforce 
+that inputs are valid, RFC-compliant URL or URI strings. 
  
-## Example 
+* [URL Constructors](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_constructors) 
+* [URL Methods](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_methods) 
+ 
+**See Also** 
+* [URL Class](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_url.htm)
+
+## Namespace
+apexdocs
+
+## Example
 In this example, the base URL and the full request URL of the current Salesforce server instance are retrieved. Next, a URL 
 pointing to a specific account object is created. Finally, components of the base and full URL are obtained. This example 
 prints out all the results to the debug log output. 
@@ -63,24 +81,6 @@ System.debug('Protocol: ' + URL.getOrgDomainURL().getProtocol());
 System.debug('Query: ' + URL.getCurrentRequestUrl().getQuery());
 ```
 
- 
-## Version Behavior Changes 
-In API version 41.0 and later, Apex URL objects are represented by the java.net.URI type, not the java.net.URL type. 
- 
-The API version in which the URL object was instantiated determines the behavior of subsequent method calls to the 
-specific instance. Salesforce strongly encourages you to use API 41.0 and later versions for fully RFC-compliant URL 
-parsing that includes proper handling of edge cases of complex URL structures. API 41.0 and later versions also enforce 
-that inputs are valid, RFC-compliant URL or URI strings. 
- 
-* [URL Constructors](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_constructors) 
-* [URL Methods](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_methods) 
- 
-**See Also** 
-* [URL Class](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_url.htm)
-
-## Namespace
-apexdocs
-
 ## Constructors
 ### `Url(spec)`
 
@@ -254,12 +254,10 @@ global static String getFileFieldURL(String entityId, String fieldName)
 The download URL for the file attachment.
 
 #### Example
-```apex
-String fileURL =
-URL.getFileFieldURL(
-  '087000000000123' ,
-  'AttachmentBody');
-```
+String fileURL = 
+URL.getFileFieldURL( 
+'087000000000123' , 
+'AttachmentBody');
 
 ---
 
@@ -306,8 +304,9 @@ global static Url getOrgDomainUrl()
 getOrgDomainUrl() always returns the login URL for your org, regardless of context. Use that URL when making API calls to your org.
 
 #### Example
+This example uses the Salesforce REST API to get organization limit values. For information on limits, see Limits in the REST API Developer Guide. 
+ 
 ```apex
-// This example uses the Salesforce REST API to get organization limit values. For information on limits, see Limits in the REST API Developer Guide.
 Http h = new Http();
 HttpRequest req = new HttpRequest();
 req.setEndpoint(Url.getOrgDomainUrl().toExternalForm()

package/examples/vitepress/docs/Sample-Enums/apexdocs.SampleEnum.md

@@ -15,6 +15,12 @@ This description has several lines
 Test. I can also have a [apexdocs.ReferencedEnum](../Miscellaneous/apexdocs.ReferencedEnum.md) here. 
 And it can be multiline.
 
+**Mermaid** 
+
+graph TD 
+A[SampleEnum] -->|references| B[ReferencedEnum] 
+B -->|referenced by| A
+
 **Group** Sample Enums
 
 **Author** John Doe
@@ -26,13 +32,6 @@ And it can be multiline.
 ## Namespace
 apexdocs
 
-## Diagram
-```mermaid
-graph TD
- A[SampleEnum] -->|references| B[ReferencedEnum]
- B -->|referenced by| A
-```
-
 ## Values
 | Value | Description |
 |-------|-------------|

package/examples/vitepress/docs/SampleGroup/apexdocs.SampleClass.md

@@ -14,10 +14,8 @@ deserunt ea officia exercitation laboris enim in duis quis enim eiusmod eu amet
 apexdocs
 
 ## Example
-```apex
-SampleClass sample = new SampleClass();
+SampleClass sample = new SampleClass(); 
 sample.doSomething();
-```
 
 **Inheritance**
 
@@ -121,10 +119,8 @@ public virtual String sayHello()
 A string value.
 
 ##### Example
-```apex
-SampleClass sample = new SampleClass();
+SampleClass sample = new SampleClass(); 
 sample.doSomething();
-```
 
 ## Classes
 ### SomeInnerClass Class

package/examples/vitepress/docs/index.md

@@ -38,78 +38,7 @@ This is a sample interface
 ### [apexdocs.Url](./Miscellaneous/apexdocs.Url.md)
 
 Represents a uniform resource locator (URL) and provides access to parts of the URL. 
-Enables access to the base URL used to access your Salesforce org. 
- 
-## Usage 
-Use the methods of the `System.URL` class to create links to objects in your organization. Such objects can be files, images, 
-logos, or records that you want to include in external emails, in activities, or in Chatter posts. For example, you can create 
-a link to a file uploaded as an attachment to a Chatter post by concatenating the Salesforce base URL with the file ID: 
- 
-```apex
-// Get a file uploaded through Chatter.
-ContentDocument doc = [SELECT Id FROM ContentDocument
-        WHERE Title = 'myfile'];
-// Create a link to the file.
-String fullFileURL = URL.getOrgDomainURL().toExternalForm() +
-        '/' + doc.id;
-System.debug(fullFileURL);
-```
-
- 
-The following example creates a link to a Salesforce record. The full URL is created by concatenating the Salesforce base 
-URL with the record ID. 
- 
-```apex
-Account acct = [SELECT Id FROM Account WHERE Name = 'Acme' LIMIT 1];
-String fullRecordURL = URL.getOrgDomainURL().toExternalForm() + '/' + acct.Id;
-```
-
- 
-## Example 
-In this example, the base URL and the full request URL of the current Salesforce server instance are retrieved. Next, a URL 
-pointing to a specific account object is created. Finally, components of the base and full URL are obtained. This example 
-prints out all the results to the debug log output. 
- 
-```apex
-// Create a new account called Acme that we will create a link for later.
-Account myAccount = new Account(Name='Acme');
-insert myAccount;
-
-// Get the base URL.
-String sfdcBaseURL = URL.getOrgDomainURL().toExternalForm();
-System.debug('Base URL: ' + sfdcBaseURL );
-
-// Get the URL for the current request.
-String currentRequestURL = URL.getCurrentRequestUrl().toExternalForm();
-System.debug('Current request URL: ' + currentRequestURL);
-
-// Create the account URL from the base URL.
-String accountURL = URL.getOrgDomainURL().toExternalForm() +
-                       '/' + myAccount.Id;
-System.debug('URL of a particular account: ' + accountURL);
-
-// Get some parts of the base URL.
-System.debug('Host: ' + URL.getOrgDomainURL().getHost());
-System.debug('Protocol: ' + URL.getOrgDomainURL().getProtocol());
-
-// Get the query string of the current request.
-System.debug('Query: ' + URL.getCurrentRequestUrl().getQuery());
-```
-
- 
-## Version Behavior Changes 
-In API version 41.0 and later, Apex URL objects are represented by the java.net.URI type, not the java.net.URL type. 
- 
-The API version in which the URL object was instantiated determines the behavior of subsequent method calls to the 
-specific instance. Salesforce strongly encourages you to use API 41.0 and later versions for fully RFC-compliant URL 
-parsing that includes proper handling of edge cases of complex URL structures. API 41.0 and later versions also enforce 
-that inputs are valid, RFC-compliant URL or URI strings. 
- 
-* [URL Constructors](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_constructors) 
-* [URL Methods](https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/apex_methods_system_url.htm#apex_System_URL_methods) 
- 
-**See Also** 
-* [URL Class](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_classes_url.htm)
+Enables access to the base URL used to access your Salesforce org.
 
 ## Sample Enums
 

package/examples/vitepress/force-app/main/default/classes/Url.cls

@@ -2,7 +2,7 @@
  * @description Represents a uniform resource locator (URL) and provides access to parts of the URL.
  * Enables access to the base URL used to access your Salesforce org.
  *
- * ## Usage
+ * @usage
  * Use the methods of the `System.URL` class to create links to objects in your organization. Such objects can be files, images,
  * logos, or records that you want to include in external emails, in activities, or in Chatter posts. For example, you can create
  * a link to a file uploaded as an attachment to a Chatter post by concatenating the Salesforce base URL with the file ID:
@@ -25,7 +25,7 @@
  * String fullRecordURL = URL.getOrgDomainURL().toExternalForm() + '/' + acct.Id;
  * ```
  *
- * ## Example
+ * @example
  * In this example, the base URL and the full request URL of the current Salesforce server instance are retrieved. Next, a URL
  * pointing to a specific account object is created. Finally, components of the base and full URL are obtained. This example
  * prints out all the results to the debug log output.
@@ -56,7 +56,7 @@
  * System.debug('Query: ' + URL.getCurrentRequestUrl().getQuery());
  * ```
  *
- * ## Version Behavior Changes
+ * @version-behavior-changes
  * In API version 41.0 and later, Apex URL objects are represented by the java.net.URI type, not the java.net.URL type.
  *
  * The API version in which the URL object was instantiated determines the behavior of subsequent method calls to the
@@ -177,7 +177,9 @@ global class Url {
      * You don't need a RemoteSiteSetting for your org to interact with the Salesforce APIs using domain URLs retrieved with this method.
      *
      * @example
-     * // This example uses the Salesforce REST API to get organization limit values. For information on limits, see Limits in the REST API Developer Guide.
+     * This example uses the Salesforce REST API to get organization limit values. For information on limits, see Limits in the REST API Developer Guide.
+     *
+     * ```apex
      * Http h = new Http();
      * HttpRequest req = new HttpRequest();
      * req.setEndpoint(Url.getOrgDomainUrl().toExternalForm()
@@ -185,6 +187,7 @@ global class Url {
      * req.setMethod('GET');
      * req.setHeader('Authorization', 'Bearer ' + UserInfo.getSessionId());
      * HttpResponse res = h.send(req);
+     * ```
      *
      * @see-also
      * * [Lightning Aura Components Developer Guide: Making API Calls from Apex](https://developer.salesforce.com/docs/atlas.en-us.250.0.lightning.meta/lightning/apex_api_calls.htm)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cparra/apexdocs",
-  "version": "2.25.0-alpha.6",
+  "version": "2.25.0-alpha.8",
   "description": "Library with CLI capabilities to generate documentation for Salesforce Apex classes.",
   "keywords": [
     "apex",

package/src/core/markdown/__test__/generating-class-docs.spec.ts

@@ -340,11 +340,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           public class MyClass {}
           `;
@@ -359,11 +361,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @example
+            * \`\`\`apex
             * public class MyClass {
             *   public void myMethod() {
             *     System.debug('Hello, World!');
             *   }
             * }
+            * \`\`\`
             */
           public class MyClass {}`;
 
@@ -669,11 +673,13 @@ describe('Generates interface documentation', () => {
         public class MyClass {
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           public void myMethod() {}
         }

package/src/core/markdown/__test__/generating-enum-docs.spec.ts

@@ -287,11 +287,13 @@ describe('Generates enum documentation', () => {
       const input = `
       /**
         * @mermaid
+        * \`\`\`mermaid
         * graph TD
         *   A[Square Rect] -- Link text --> B((Circle))
         *   A --> C(Round Rect)
         *   B --> D{Rhombus}
         *   C --> D
+        * \`\`\`
         */
       public enum MyEnum {
         VALUE1,
@@ -309,11 +311,13 @@ describe('Generates enum documentation', () => {
       const input = `
       /**
         * @example
+        * \`\`\`apex
         * public class MyClass {
         *   public void myMethod() {
         *     System.debug('Hello, World!');
         *   }
         * }
+        * \`\`\`
         */
       public enum MyEnum {
         VALUE1,

package/src/core/markdown/__test__/generating-interface-docs.spec.ts

@@ -261,11 +261,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           public interface MyInterface {}
           `;
@@ -280,11 +282,13 @@ describe('Generates interface documentation', () => {
         const input = `
           /**
             * @example
+            * \`\`\`apex
             * public class MyClass {
             *   public void myMethod() {
             *     System.debug('Hello, World!');
             *   }
             * }
+            * \`\`\`
             */
           public interface MyInterface {}`;
 
@@ -343,11 +347,13 @@ describe('Generates interface documentation', () => {
         public interface MyInterface {
           /**
             * @mermaid
+            * \`\`\`mermaid
             * graph TD
             *   A[Square Rect] -- Link text --> B((Circle))
             *   A --> C(Round Rect)
             *   B --> D{Rhombus}
             *   C --> D
+            * \`\`\`
             */
           void myMethod();
         }

package/src/core/markdown/adapters/documentables.ts

@@ -1,4 +1,4 @@
-import { CustomTag, RenderableDocumentation, RenderableContent, CodeBlock } from './types';
+import { CustomTag, RenderableDocumentation, RenderableContent } from './types';
 import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
 import { replaceInlineReferences } from './inline';
 import { isEmptyLine } from './type-utils';
@@ -9,59 +9,62 @@ export function adaptDescribable(
 ): {
   description?: RenderableContent[];
 } {
-  function describableToRenderableContent(describable: Describable): RenderableContent[] | undefined {
-    if (!describable) {
-      return;
-    }
+  return {
+    description: describableToRenderableContent(describable, linkGenerator),
+  };
+}
 
-    let content: RenderableContent[] = [];
-    for (let i = 0; i < describable.length; i++) {
-      const line = describable[i];
-      // The language might or might not be present after ```
-      const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
-      if (codeBlockMatch) {
-        // Check if the language is present, if not, fallback to "apex"
-        const language = codeBlockMatch[1] || 'apex';
-        const codeBlockLines: string[] = [];
-        i++;
-        while (i < describable.length) {
-          const currentLine = describable[i];
-          if (currentLine.trim() === '```') {
-            break;
-          }
-          codeBlockLines.push(currentLine);
-          i++;
+export function describableToRenderableContent(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): RenderableContent[] | undefined {
+  if (!describable) {
+    return;
+  }
+
+  let content: RenderableContent[] = [];
+  for (let i = 0; i < describable.length; i++) {
+    const line = describable[i];
+    // The language might or might not be present after ```
+    const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
+    if (codeBlockMatch) {
+      // Check if the language is present, if not, fallback to "apex"
+      const language = codeBlockMatch[1] || 'apex';
+      const codeBlockLines: string[] = [];
+      i++;
+      while (i < describable.length) {
+        const currentLine = describable[i];
+        if (currentLine.trim() === '```') {
+          break;
         }
-        content = [
-          ...content,
-          {
-            __type: 'code-block',
-            language,
-            content: codeBlockLines,
-          },
-          { __type: 'empty-line' },
-        ];
-        continue;
+        codeBlockLines.push(currentLine);
+        i++;
       }
-
       content = [
         ...content,
-        ...replaceInlineReferences(line, linkGenerator),
         {
-          __type: 'empty-line',
+          __type: 'code-block',
+          language,
+          content: codeBlockLines,
         },
+        { __type: 'empty-line' },
       ];
+      continue;
     }
-    return (
-      content
-        // If the last element is an empty line, remove it
-        .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
-    );
-  }
 
-  return {
-    description: describableToRenderableContent(describable),
-  };
+    content = [
+      ...content,
+      ...replaceInlineReferences(line, linkGenerator),
+      {
+        __type: 'empty-line',
+      },
+    ];
+  }
+  return (
+    content
+      // If the last element is an empty line, remove it
+      .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
+  );
 }
 
 export function adaptDocumentable(
@@ -70,7 +73,7 @@ export function adaptDocumentable(
   subHeadingLevel: number,
 ): RenderableDocumentation {
   function extractCustomTags(type: Documentable): CustomTag[] {
-    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'mermaid', 'throws', 'exception'];
+    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'throws', 'exception'];
 
     return (
       type.docComment?.annotations
@@ -82,12 +85,6 @@ export function adaptDocumentable(
     );
   }
 
-  function extractAnnotationBodyLines(type: Documentable, annotationName: string): string[] | undefined {
-    return type.docComment?.annotations.find(
-      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
-    )?.bodyLines;
-  }
-
   function extractAnnotationBody(type: Documentable, annotationName: string): string | undefined {
     return type.docComment?.annotations.find(
       (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
@@ -102,30 +99,14 @@ export function adaptDocumentable(
     );
   }
 
-  function bodyLinesToCodeBlock(language: string, bodyLines: string[] | undefined): CodeBlock | undefined {
-    if (!bodyLines) {
-      return;
-    }
-    return {
-      __type: 'code-block',
-      language,
-      content: bodyLines,
-    };
-  }
-
   return {
     ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
     customTags: extractCustomTags(documentable),
-    mermaid: {
-      headingLevel: subHeadingLevel,
-      heading: 'Diagram',
-      value: bodyLinesToCodeBlock('mermaid', extractAnnotationBodyLines(documentable, 'mermaid')),
-    },
     example: {
       headingLevel: subHeadingLevel,
       heading: 'Example',
-      value: bodyLinesToCodeBlock('apex', documentable.docComment?.exampleAnnotation?.bodyLines),
+      value: describableToRenderableContent(documentable.docComment?.exampleAnnotation?.bodyLines, linkGenerator),
     },
     group: extractAnnotationBody(documentable, 'group'),
     author: extractAnnotationBody(documentable, 'author'),

package/src/core/markdown/adapters/types.d.ts

@@ -84,8 +84,7 @@ type RenderableDocumentation = {
   annotations?: Annotation[];
   description?: RenderableContent[];
   customTags?: CustomTag[];
-  mermaid: RenderableSection<CodeBlock | undefined>;
-  example: RenderableSection<CodeBlock | undefined>;
+  example: RenderableSection<RenderableContent[] | undefined>;
   group?: string;
   author?: string;
   date?: string;

package/src/core/markdown/templates/documentable-partial-template.ts

@@ -21,6 +21,6 @@ export const documentablePartialTemplate = `
 
 {{#if doc.example.value}}
 {{ heading doc.example.headingLevel doc.example.heading }}
-{{code doc.example.value}}
+{{{renderContent doc.example.value}}}
 {{/if}}
 `.trim();