Merge pull request #108 from cesarParra/mermaid-support

Mermaid support.

README.md

@@ -357,6 +357,31 @@ To fix this issue, when not sanitizing HTML, you should wrap any code that conta
 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.
+
+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.
+
+**Example**
+
+```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 {
+}
+```
+
+[Here's an example of how that looks](/docs/types/Classes/nspc.AnotherInterface.md)
 
 ### Ignoring files and members
 

docs/types/Classes/nspc.AnotherInterface.md

@@ -5,3 +5,18 @@ Some desc
 
 **Group** Classes
 
+
+```mermaid
+sequenceDiagram
+    participant dotcom
+    participant iframe
+    participant viewscreen
+    dotcom->>iframe: loads html w/ iframe url
+    iframe->>viewscreen: request template
+    viewscreen->>iframe: html & javascript
+    iframe->>dotcom: iframe ready
+    dotcom->>iframe: set mermaid data on iframe
+    iframe->>iframe: render mermaid
+```
+
+

docs/types/Classes/nspc.ChildClass.md

@@ -58,6 +58,21 @@ This method was overridden.
 |---|---|
 |`String`|A String.|
 
+
+```mermaid
+sequenceDiagram
+    participant dotcom
+    participant iframe
+    participant viewscreen
+    dotcom->>iframe: loads html w/ iframe url
+    iframe->>viewscreen: request template
+    viewscreen->>iframe: html & javascript
+    iframe->>dotcom: iframe ready
+    dotcom->>iframe: set mermaid data on iframe
+    iframe->>iframe: render mermaid
+```
+
+
 ### `public void execute()`
 
 Executes the command.

examples/force-app/main/default/classes/AnotherInterface.cls

@@ -1,5 +1,16 @@
 /**
  * @description Some desc
  * @group Classes
+ * @mermaid
+  * sequenceDiagram
+  *     participant dotcom
+  *     participant iframe
+  *     participant viewscreen
+  *     dotcom->>iframe: loads html w/ iframe url
+  *     iframe->>viewscreen: request template
+  *     viewscreen->>iframe: html & javascript
+  *     iframe->>dotcom: iframe ready
+  *     dotcom->>iframe: set mermaid data on iframe
+  *     iframe->>iframe: render mermaid
  */
 public interface AnotherInterface{}

examples/force-app/main/default/classes/ChildClass.cls

@@ -12,6 +12,17 @@ public class ChildClass extends ParentClass implements SampleInterface {
     /**
      * @description This method was overridden.
      * @return A String.
+     * @mermaid
+     * sequenceDiagram
+     *     participant dotcom
+     *     participant iframe
+     *     participant viewscreen
+     *     dotcom->>iframe: loads html w/ iframe url
+     *     iframe->>viewscreen: request template
+     *     viewscreen->>iframe: html & javascript
+     *     iframe->>dotcom: iframe ready
+     *     dotcom->>iframe: set mermaid data on iframe
+     *     iframe->>iframe: render mermaid
      */
     public override String overridableMethodOverridden() {
         return null ?? '';

package.json

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

src/model/markdown-file.ts

@@ -26,8 +26,8 @@ export class MarkdownFile extends OutputFile {
     this.addText(`\{@link ${text}\}`, encodeHtml);
   }
 
-  startCodeBlock() {
-    this.addText('```apex');
+  startCodeBlock(language = 'apex') {
+    this.addText(`\`\`\`${language}`);
   }
 
   endCodeBlock() {

src/model/markdown-generation-util/doc-comment-annotation-util.ts

@@ -6,9 +6,25 @@ interface DocCommentAware {
   docComment?: DocComment;
 }
 
+export function addMermaid(markdownFile: MarkdownFile, docCommentAware: DocCommentAware) {
+  const mermaid = docCommentAware.docComment?.annotations.find((annotation) => annotation.name === 'mermaid');
+  if (!mermaid) {
+    return;
+  }
+
+  markdownFile.addBlankLine();
+  markdownFile.startCodeBlock('mermaid');
+  mermaid.bodyLines.forEach((line) => {
+    markdownFile.addText(line, false);
+  });
+  markdownFile.endCodeBlock();
+  markdownFile.addBlankLine();
+}
+
 export function addCustomDocCommentAnnotations(markdownFile: MarkdownFile, docCommentAware: DocCommentAware) {
   docCommentAware.docComment?.annotations
     .filter((currentAnnotation: DocCommentAnnotation) => currentAnnotation.name !== 'description')
+    .filter((currentAnnotation: DocCommentAnnotation) => currentAnnotation.name !== 'mermaid')
     .forEach((currentAnnotation: DocCommentAnnotation) => {
       markdownFile.addBlankLine();
       markdownFile.addText(buildDocAnnotationText(currentAnnotation));

src/model/markdown-generation-util/method-declaration-util.ts

@@ -1,7 +1,7 @@
 import { ConstructorMirror, DocComment } from '@cparra/apex-reflection';
 import { MarkdownFile } from '../markdown-file';
 import { ParameterMirror } from '@cparra/apex-reflection';
-import { addCustomDocCommentAnnotations } from './doc-comment-annotation-util';
+import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
 import { MethodMirrorWithInheritance } from '../inheritance';
 
 export function declareMethod(
@@ -55,6 +55,8 @@ export function declareMethod(
 
     addCustomDocCommentAnnotations(markdownFile, currentMethod);
 
+    addMermaid(markdownFile, currentMethod);
+
     if (currentMethod.docComment?.exampleAnnotation) {
       addExample(markdownFile, currentMethod, startingHeadingLevel);
     }

src/model/markdown-generation-util/type-declaration-util.ts

@@ -1,5 +1,5 @@
 import { MarkdownFile } from '../markdown-file';
-import { addCustomDocCommentAnnotations } from './doc-comment-annotation-util';
+import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
 import { Annotation, ClassMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
 import { TypesRepository } from '../types-repository';
 
@@ -26,6 +26,8 @@ export function declareType(markdownFile: MarkdownFile, typeMirror: Type): void
   }
 
   addCustomDocCommentAnnotations(markdownFile, typeMirror);
+
+  addMermaid(markdownFile, typeMirror);
 }
 
 function addInheritanceSectionForClass(typeMirror: Type, markdownFile: MarkdownFile) {