@cparra/apexdocs 3.0.0-rc.0 → 3.1.0

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

@@ -1,397 +0,0 @@
-import { assertEither, extendExpect } from './expect-extensions';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-
-describe('Generates interface documentation', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  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 = `
-        public interface MyInterface {
-          void myMethod();
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('## Methods'));
-      });
-
-      it('displays methods sorted if sortMembersAlphabetically is true', async () => {
-        const input = `
-        public interface MyInterface {
-          void myMethod();
-          void anotherMethod();
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: 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 () => {
-        const input = `
-        public interface MyInterface {
-          void myMethod();
-          void anotherMethod();
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => {
-          expect(data.docs[0].content.indexOf('myMethod')).toBeLessThan(data.docs[0].content.indexOf('anotherMethod'));
-        });
-      });
-
-      it('supports having mermaid diagrams in method descriptions', async () => {
-        const input = `
-        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();
-        }
-      `;
-
-        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('supports having example code blocks in method descriptions', async () => {
-        const input = `
-        public interface MyInterface {
-          /**
-            * @example
-            * public class MyClass {
-            *   public void myMethod() {
-            *     System.debug('Hello, World!');
-            *   }
-            * }
-            */
-          void myMethod();
-        }
-      `;
-
-        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('has a signature section', async () => {
-        const input = `
-        public interface MyInterface {
-          void myMethod();
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('### Signature'));
-      });
-
-      it('has a parameters section', async () => {
-        const input = `
-        public interface MyInterface {
-          void myMethod(String param1, Integer param2);
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('### Parameters'));
-      });
-
-      it('has a return type section', async () => {
-        const input = `
-        public interface MyInterface {
-          String myMethod();
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('### Return Type'));
-      });
-
-      it('has a throws section', async () => {
-        const input = `
-        public interface MyInterface {
-          /**
-            * @throws MyException
-            */
-          void myMethod();
-        }
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains('### Throws'));
-      });
-
-      it('displays an "inherited" tag if the method was inherited from a different interface', async () => {
-        const input1 = `
-        public interface MyInterface {
-          void myMethod();
-        }
-      `;
-
-        const input2 = `
-        public interface AnotherInterface extends MyInterface {}
-      `;
-
-        const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-        expect(result).documentationBundleHasLength(2);
-        assertEither(result, (data) =>
-          expect(data.docs.find((doc) => doc.outputDocPath.includes('AnotherInterface'))?.content).toContain(
-            'Inherited',
-          ),
-        );
-      });
-    });
-  });
-});

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

@@ -1,180 +0,0 @@
-import { assertEither, extendExpect } from './expect-extensions';
-import { pipe } from 'fp-ts/function';
-import * as E from 'fp-ts/Either';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-import { ReferenceGuidePageData } from '../../shared/types';
-
-describe('Generates a Reference Guide', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  it('returns a reference guide with links to all other files', async () => {
-    const input1 = `
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyEnum](miscellaneous/MyEnum.md)'),
-    );
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('[MyClass](miscellaneous/MyClass.md)'),
-    );
-  });
-
-  it('groups things under Miscellaneous if no group is provided', async () => {
-    const input = `
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input)])();
-    expect(result).documentationBundleHasLength(1);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('## Miscellaneous'),
-    );
-  });
-
-  it('group things under the provided 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.referenceGuide as ReferenceGuidePageData).content).toContain('## MyGroup'),
-    );
-  });
-
-  it('displays groups in alphabetical order', async () => {
-    const input1 = `
-      /**
-        * @group ZGroup
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @group AGroup
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    pipe(
-      result,
-      E.map((data) => ({
-        aGroupIndex: (data.referenceGuide as ReferenceGuidePageData).content.indexOf('## AGroup'),
-        zGroupIndex: (data.referenceGuide as ReferenceGuidePageData).content.indexOf('## ZGroup'),
-      })),
-      E.match(
-        () => fail('Expected data'),
-        (data) => expect(data.aGroupIndex).toBeLessThan(data.zGroupIndex),
-      ),
-    );
-  });
-
-  it('displays references within groups in alphabetical order', async () => {
-    const input1 = `
-      /**
-        * @group Group1
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @group Group1
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('## Group1'),
-    );
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('MyClass'),
-    );
-    assertEither(result, (data) => expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('MyEnum'));
-  });
-
-  it('returns a reference guide with descriptions', async () => {
-    const input1 = `
-      /**
-        * @description This is a description
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @description This is a description
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('This is a description'),
-    );
-  });
-
-  it('returns a reference guide with descriptions with links to all other files', async () => {
-    const input1 = `
-      /**
-        * @description This is a description with a {@link MyClass}
-        * @group Group1
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-    const input2 = `
-      /**
-        * @group Group2
-        */
-      public class MyClass {}
-      `;
-
-    const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-    expect(result).documentationBundleHasLength(2);
-    assertEither(result, (data) =>
-      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('with a [MyClass](group2/MyClass.md)'),
-    );
-  });
-});

package/src/core/markdown/__test__/inheritance-chain.test.ts

@@ -1,54 +0,0 @@
-import { ClassMirrorBuilder } from '../../../test-helpers/ClassMirrorBuilder';
-import { createInheritanceChain } from '../reflection/inheritance-chain';
-
-describe('inheritance chain for classes', () => {
-  test('returns an empty list of the class does not extend any other class', () => {
-    const classMirror = new ClassMirrorBuilder().build();
-    const repository = [classMirror];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual([]);
-  });
-
-  test('returns the name of the extended class if it is not found in the repository', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
-    const repository = [classMirror];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['ExtendedClass']);
-  });
-
-  test('returns the extended class when it is present in the repository', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
-    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').build();
-    const repository = [classMirror, extendedClass];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['ExtendedClass']);
-  });
-
-  test('returns the full inheritance chain when the extended class is also extended', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
-    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').withExtendedClass('SuperClass').build();
-    const superClass = new ClassMirrorBuilder().withName('SuperClass').build();
-    const repository = [classMirror, extendedClass, superClass];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['ExtendedClass', 'SuperClass']);
-  });
-
-  test('returns the inheritance for a class that extends an inner class', () => {
-    const classMirror = new ClassMirrorBuilder().withExtendedClass('OuterClass.InnerClass').build();
-    const innerClass = new ClassMirrorBuilder().withName('InnerClass').build();
-    const outerClass = new ClassMirrorBuilder().withName('OuterClass').addInnerClass(innerClass).build();
-    const repository = [classMirror, outerClass];
-
-    const inheritanceChain = createInheritanceChain(repository, classMirror);
-
-    expect(inheritanceChain).toEqual(['OuterClass.InnerClass']);
-  });
-});

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

@@ -1,23 +0,0 @@
-import { UnparsedSourceFile } from '../../shared/types';
-import { generateDocs as gen, MarkdownGeneratorConfig } from '../generate-docs';
-import { referenceGuideTemplate } from '../templates/reference-guide';
-
-export function apexBundleFromRawString(raw: string, rawMetadata?: string): UnparsedSourceFile {
-  return {
-    filePath: 'test.cls',
-    content: raw,
-    metadataContent: rawMetadata ?? null,
-  };
-}
-
-export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial<MarkdownGeneratorConfig>) {
-  return gen(apexBundles, {
-    targetDir: 'target',
-    scope: ['global', 'public'],
-    defaultGroupName: 'Miscellaneous',
-    sortMembersAlphabetically: true,
-    referenceGuideTemplate: referenceGuideTemplate,
-    linkingStrategy: 'relative',
-    ...config,
-  });
-}