@cparra/apexdocs 3.0.0-rc.0 → 3.0.0

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

@@ -7,266 +7,6 @@ describe('Generates enum documentation', () => {
   });
 
   describe('documentation content', () => {
-    it('generates a heading with the enum name', async () => {
-      const input = `
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const output = `# MyEnum Enum`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains(output));
-    });
-
-    it('displays type level annotations', async () => {
-      const input = `
-        @NamespaceAccessible
-        public enum MyEnum {
-           VALUE1,
-           VALUE2
-         }
-       `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('NAMESPACEACCESSIBLE'));
-    });
-
-    it('displays the description', async () => {
-      const input = `
-     /**
-      * This is a description
-      */
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
-    });
-
-    it('display custom documentation tags', async () => {
-      const input = `
-     /**
-      * @custom-tag My Value
-      */
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('Custom Tag'));
-      assertEither(result, (data) => expect(data).firstDocContains('My Value'));
-    });
-
-    it('displays the group', async () => {
-      const input = `
-     /**
-      * @group MyGroup
-      */
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('Group'));
-      assertEither(result, (data) => expect(data).firstDocContains('MyGroup'));
-    });
-
-    it('displays the author', async () => {
-      const input = `
-     /**
-      * @author John Doe
-      */
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('Author'));
-      assertEither(result, (data) => expect(data).firstDocContains('John Doe'));
-    });
-
-    it('displays the date', async () => {
-      const input = `
-     /**
-      * @date 2021-01-01
-      */
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('Date'));
-      assertEither(result, (data) => expect(data).firstDocContains('2021-01-01'));
-    });
-
-    it('displays descriptions', async () => {
-      const input = `
-      /**
-        * @description This is a description
-        */
-      public enum MyEnum {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
-    });
-
-    it('displays descriptions with links', async () => {
-      const input1 = `
-      /**
-        * @description This is a description with a {@link EnumRef} reference
-        */
-      public enum MyEnum {}
-      `;
-
-      const input2 = 'public enum EnumRef {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-      expect(result).documentationBundleHasLength(2);
-      assertEither(result, (data) => expect(data).firstDocContains('Description'));
-      assertEither(result, (data) =>
-        expect(data).firstDocContains('This is a description with a [EnumRef](EnumRef.md) reference'),
-      );
-    });
-
-    it('displays descriptions with emails', async () => {
-      const input = `
-      /**
-        * @description This is a description with an {@email test@testerson.com} email
-        */
-      public enum MyEnum {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) =>
-        expect(data).firstDocContains(
-          'This is a description with an [test@testerson.com](mailto:test@testerson.com) email',
-        ),
-      );
-    });
-
-    it('displays sees with accurately resolved links', async () => {
-      const input1 = `
-      /**
-        * @see EnumRef
-        */
-      public enum MyEnum {}
-      `;
-
-      const input2 = 'public enum EnumRef {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-      expect(result).documentationBundleHasLength(2);
-      assertEither(result, (data) => expect(data).firstDocContains('See'));
-      assertEither(result, (data) => expect(data).firstDocContains('[EnumRef](EnumRef.md)'));
-    });
-
-    it('displays sees without links when the reference is not found', async () => {
-      const input = `
-      /**
-        * @see EnumRef
-        */
-      public enum MyEnum {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('See'));
-      assertEither(result, (data) => expect(data).firstDocContains('EnumRef'));
-    });
-
-    it('displays the namespace if present in the config', async () => {
-      const input = `
-      public enum MyEnum {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { namespace: 'MyNamespace' })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Namespace'));
-      assertEither(result, (data) => expect(data).firstDocContains('MyNamespace'));
-    });
-
-    it('does not display the namespace if not present in the config', async () => {
-      const input = `
-      public enum MyEnum {}
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContainsNot('## Namespace'));
-    });
-
-    it('displays a mermaid diagram', async () => {
-      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,
-        VALUE2
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('```mermaid'));
-      assertEither(result, (data) => expect(data).firstDocContains('graph TD'));
-    });
-
-    it('displays an example code block', async () => {
-      const input = `
-      /**
-        * @example
-        * \`\`\`apex
-        * public class MyClass {
-        *   public void myMethod() {
-        *     System.debug('Hello, World!');
-        *   }
-        * }
-        * \`\`\`
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('```apex'));
-      assertEither(result, (data) => expect(data).firstDocContains('public class MyClass'));
-    });
-
     it('displays values', async () => {
       const input = `
       public enum MyEnum {
@@ -282,7 +22,7 @@ describe('Generates enum documentation', () => {
       assertEither(result, (data) => expect(data).firstDocContains('VALUE2'));
     });
 
-    it('displays values sorted when sortMembersAlphabetically is true', async () => {
+    it('displays values sorted when sortAlphabetically is true', async () => {
       const input = `
       public enum MyEnum {
         VALUE2,
@@ -290,7 +30,7 @@ describe('Generates enum documentation', () => {
       }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => expect(data).firstDocContains('## Values'));
       assertEither(result, (data) => {
@@ -300,7 +40,7 @@ describe('Generates enum documentation', () => {
       });
     });
 
-    it('does not sort values when sortMembersAlphabetically is false', async () => {
+    it('does not sort values when sortAlphabetically is false', async () => {
       const input = `
       public enum MyEnum {
         VALUE2,
@@ -308,7 +48,7 @@ describe('Generates enum documentation', () => {
       }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => expect(data).firstDocContains('## Values'));
       assertEither(result, (data) => {

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

@@ -7,234 +7,6 @@ describe('Generates interface documentation', () => {
   });
 
   describe('documentation content', () => {
-    describe('type level information', () => {
-      it('generates a heading with the interface name', async () => {
-        const input = `
-        public interface MyInterface {}
-      `;
-
-        const output = `# MyInterface Interface`;
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains(output));
-      });
-
-      it('displays type level annotations', async () => {
-        const input = `
-        @NamespaceAccessible
-        public interface MyInterface {
-          @Deprecated
-          void myMethod();   
-        }
-       `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('NAMESPACEACCESSIBLE'));
-        assertEither(result, (data) => expect(data).firstDocContains('DEPRECATED'));
-      });
-
-      it('displays the description', async () => {
-        const input = `
-          /**
-           * This is a description
-           */
-          public interface MyInterface {}
-         `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
-      });
-
-      it('display custom documentation tags', async () => {
-        const input = `
-          /**
-           * @custom-tag My Value
-           */
-          public interface MyInterface {}
-        `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('Custom Tag'));
-        assertEither(result, (data) => expect(data).firstDocContains('My Value'));
-      });
-
-      it('displays the group', async () => {
-        const input = `
-          /**
-           * @group MyGroup
-           */
-          public interface MyInterface {}`;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('Group'));
-        assertEither(result, (data) => expect(data).firstDocContains('MyGroup'));
-      });
-
-      it('displays the author', async () => {
-        const input = `
-          /**
-           * @author John Doe
-           */
-          public interface MyInterface {}`;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('Author'));
-        assertEither(result, (data) => expect(data).firstDocContains('John Doe'));
-      });
-
-      it('displays the date', async () => {
-        const input = `
-          /**
-           * @date 2021-01-01
-           */
-          public interface MyInterface {}`;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('Date'));
-        assertEither(result, (data) => expect(data).firstDocContains('2021-01-01'));
-      });
-
-      it('displays descriptions', async () => {
-        const input = `
-          /**
-            * @description This is a description
-            */
-          public interface MyInterface {}`;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
-      });
-
-      it('displays descriptions with links', async () => {
-        const input1 = `
-          /**
-            * @description This is a description with a {@link InterfaceRef} reference
-            */
-          public enum MyInterface {}
-          `;
-
-        const input2 = 'public interface InterfaceRef {}';
-
-        const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-        expect(result).documentationBundleHasLength(2);
-        assertEither(result, (data) =>
-          expect(data).firstDocContains('This is a description with a [InterfaceRef](InterfaceRef.md) reference'),
-        );
-      });
-
-      it('displays descriptions with emails', async () => {
-        const input = `
-          /**
-            * @description This is a description with an {@email test@testerson.com} email
-            */
-          public interface MyInterface {}
-          `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) =>
-          expect(data).firstDocContains(
-            'This is a description with an [test@testerson.com](mailto:test@testerson.com) email',
-          ),
-        );
-      });
-
-      it('displays sees with accurately resolved links', async () => {
-        const input1 = `
-          /**
-            * @see InterfaceRef
-            */
-          public interface MyInterface {}
-          `;
-
-        const input2 = 'public interface InterfaceRef {}';
-
-        const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-        expect(result).documentationBundleHasLength(2);
-        assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('[InterfaceRef](InterfaceRef.md)'));
-      });
-
-      it('displays sees without links when the reference is not found', async () => {
-        const input = `
-          /**
-            * @see InterfaceRef
-            */
-          public interface MyInterface {}
-          `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('See'));
-        assertEither(result, (data) => expect(data).firstDocContains('InterfaceRef'));
-      });
-
-      it('displays the namespace if present in the config', async () => {
-        const input = 'public interface MyInterface {}';
-
-        const result = await generateDocs([apexBundleFromRawString(input)], { namespace: 'MyNamespace' })();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('## Namespace'));
-        assertEither(result, (data) => expect(data).firstDocContains('MyNamespace'));
-      });
-
-      it('does not display the namespace if not present in the config', async () => {
-        const input = 'public interface MyInterface {}';
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContainsNot('## Namespace'));
-      });
-
-      it('displays a mermaid diagram', async () => {
-        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 {}
-          `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('```mermaid'));
-        assertEither(result, (data) => expect(data).firstDocContains('graph TD'));
-      });
-
-      it('displays an example code block', async () => {
-        const input = `
-          /**
-            * @example
-            * \`\`\`apex
-            * public class MyClass {
-            *   public void myMethod() {
-            *     System.debug('Hello, World!');
-            *   }
-            * }
-            * \`\`\`
-            */
-          public interface MyInterface {}`;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('```apex'));
-        assertEither(result, (data) => expect(data).firstDocContains('public class MyClass'));
-      });
-    });
-
     describe('method information', () => {
       it('displays the Method heading', async () => {
         const input = `
@@ -248,7 +20,7 @@ describe('Generates interface documentation', () => {
         assertEither(result, (data) => expect(data).firstDocContains('## Methods'));
       });
 
-      it('displays methods sorted if sortMembersAlphabetically is true', async () => {
+      it('displays methods sorted if sortAlphabetically is true', async () => {
         const input = `
         public interface MyInterface {
           void myMethod();
@@ -256,14 +28,14 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-        const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+        const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => {
           expect(data.docs[0].content.indexOf('anotherMethod')).toBeLessThan(data.docs[0].content.indexOf('myMethod'));
         });
       });
 
-      it('does not display methods sorted if sortMembersAlphabetically is false', async () => {
+      it('does not display methods sorted if sortAlphabetically is false', async () => {
         const input = `
         public interface MyInterface {
           void myMethod();
@@ -271,7 +43,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-        const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+        const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => {
           expect(data.docs[0].content.indexOf('myMethod')).toBeLessThan(data.docs[0].content.indexOf('anotherMethod'));

package/src/core/markdown/__test__/generating-reference-guide.spec.ts

@@ -4,11 +4,27 @@ import * as E from 'fp-ts/Either';
 import { apexBundleFromRawString, generateDocs } from './test-helpers';
 import { ReferenceGuidePageData } from '../../shared/types';
 
-describe('Generates a Reference Guide', () => {
+describe('When generating the Reference Guide', () => {
   beforeAll(() => {
     extendExpect();
   });
 
+  it('contains the correct default title by default', async () => {
+    const result = await generateDocs([])();
+
+    assertEither(result, (data) =>
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('# Apex Reference Guide'),
+    );
+  });
+
+  it('allows for the reference guide title to be configured', async () => {
+    const result = await generateDocs([], { referenceGuideTitle: 'Custom Title' })();
+
+    assertEither(result, (data) =>
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('# Custom Title'),
+    );
+  });
+
   it('returns a reference guide with links to all other files', async () => {
     const input1 = `
       public enum MyEnum {

package/src/core/markdown/__test__/test-helpers.ts

@@ -15,9 +15,11 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     targetDir: 'target',
     scope: ['global', 'public'],
     defaultGroupName: 'Miscellaneous',
-    sortMembersAlphabetically: true,
+    sortAlphabetically: false,
     referenceGuideTemplate: referenceGuideTemplate,
     linkingStrategy: 'relative',
+    excludeTags: [],
+    referenceGuideTitle: 'Apex Reference Guide',
     ...config,
   });
 }

package/src/core/markdown/adapters/__tests__/interface-adapter.spec.ts

@@ -14,8 +14,10 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
   namespace: '',
   defaultGroupName: 'Miscellaneous',
   referenceGuideTemplate: '',
-  sortMembersAlphabetically: false,
+  sortAlphabetically: false,
   linkingStrategy: 'relative',
+  referenceGuideTitle: 'Apex Reference Guide',
+  excludeTags: [],
 };
 
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

package/src/core/markdown/adapters/renderable-to-page-data.ts

@@ -5,15 +5,16 @@ import { CompilationRequest, Template } from '../templates/template';
 import { enumMarkdownTemplate } from '../templates/enum-template';
 import { interfaceMarkdownTemplate } from '../templates/interface-template';
 import { classMarkdownTemplate } from '../templates/class-template';
-import { defaults } from '../../../defaults';
+import { markdownDefaults } from '../../../defaults';
 
 export const convertToDocumentationBundle = (
+  referenceGuideTitle: string,
   referenceGuideTemplate: string,
   { referencesByGroup, renderables }: RenderableBundle,
 ): DocumentationBundle => ({
   referenceGuide: {
     frontmatter: null,
-    content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
+    content: referencesToReferenceGuideContent(referenceGuideTitle, referencesByGroup, referenceGuideTemplate),
     outputDocPath: 'index.md',
   },
   docs: renderables.map((renderable: Renderable) =>
@@ -22,6 +23,7 @@ export const convertToDocumentationBundle = (
 });
 
 function referencesToReferenceGuideContent(
+  referenceGuideTitle: string,
   references: { [key: string]: ReferenceGuideReference[] },
   template: string,
 ): string {
@@ -39,7 +41,7 @@ function referencesToReferenceGuideContent(
   return pipe(references, alphabetizeReferences, (references) =>
     compile({
       template: template,
-      source: references,
+      source: { referenceGuideTitle: referenceGuideTitle, references },
     }),
   );
 }
@@ -59,7 +61,7 @@ function renderableToPageData(referenceGuideReference: ReferenceGuideReference[]
       outputDocPath: reference!.reference.outputDocPath,
       frontmatter: null,
       content: docContents,
-      group: renderable.doc.group ?? defaults.defaultGroupName,
+      group: renderable.doc.group ?? markdownDefaults.defaultGroupName,
     };
   }