diff --git a/README.md b/README.md index e14acc09..ed738d0f 100644 --- a/README.md +++ b/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 `` 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 diff --git a/docs/types/Classes/nspc.AnotherInterface.md b/docs/types/Classes/nspc.AnotherInterface.md index 8f7a766b..96a6b0ca 100644 --- a/docs/types/Classes/nspc.AnotherInterface.md +++ b/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 +``` + + diff --git a/docs/types/Classes/nspc.ChildClass.md b/docs/types/Classes/nspc.ChildClass.md index ee6084de..bee452bf 100644 --- a/docs/types/Classes/nspc.ChildClass.md +++ b/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. diff --git a/examples/force-app/main/default/classes/AnotherInterface.cls b/examples/force-app/main/default/classes/AnotherInterface.cls index f4b12aa0..28ff7ba3 100644 --- a/examples/force-app/main/default/classes/AnotherInterface.cls +++ b/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{} diff --git a/examples/force-app/main/default/classes/ChildClass.cls b/examples/force-app/main/default/classes/ChildClass.cls index 5834caf4..6daa36cb 100644 --- a/examples/force-app/main/default/classes/ChildClass.cls +++ b/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 ?? ''; diff --git a/package.json b/package.json index ba52ced7..57684f20 100644 --- a/package.json +++ b/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", diff --git a/src/model/markdown-file.ts b/src/model/markdown-file.ts index c4ca6765..9e68832d 100644 --- a/src/model/markdown-file.ts +++ b/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() { diff --git a/src/model/markdown-generation-util/doc-comment-annotation-util.ts b/src/model/markdown-generation-util/doc-comment-annotation-util.ts index 6c3eac7d..ba8c60ca 100644 --- a/src/model/markdown-generation-util/doc-comment-annotation-util.ts +++ b/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)); diff --git a/src/model/markdown-generation-util/method-declaration-util.ts b/src/model/markdown-generation-util/method-declaration-util.ts index 7cc38c3b..f352ce8f 100644 --- a/src/model/markdown-generation-util/method-declaration-util.ts +++ b/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); } diff --git a/src/model/markdown-generation-util/type-declaration-util.ts b/src/model/markdown-generation-util/type-declaration-util.ts index c5374d8d..32b739d2 100644 --- a/src/model/markdown-generation-util/type-declaration-util.ts +++ b/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) {