@cparra/apexdocs 3.0.0 → 3.1.0

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

@@ -1,378 +0,0 @@
-import { DocPageData, PostHookDocumentationBundle } from '../../shared/types';
-import { assertEither, extendExpect } from './expect-extensions';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-
-function aSingleDoc(result: PostHookDocumentationBundle): DocPageData {
-  expect(result.docs).toHaveLength(1);
-  return result.docs[0];
-}
-
-describe('When generating documentation', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  describe('the resulting files', () => {
-    it('are named after the type', async () => {
-      const properties: [string, string][] = [
-        ['public class MyClass {}', 'MyClass.md'],
-        ['public interface MyInterface {}', 'MyInterface.md'],
-        ['public enum MyEnum {}', 'MyEnum.md'],
-      ];
-
-      for (const [input, expected] of properties) {
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        assertEither(result, (data) => expect(aSingleDoc(data).outputDocPath).toContain(expected));
-      }
-    });
-
-    it('are placed in the miscellaneous folder if no group is provided', async () => {
-      const properties: [string, string][] = [
-        ['public class MyClass {}', 'miscellaneous'],
-        ['public interface MyInterface {}', 'miscellaneous'],
-        ['public enum MyEnum {}', 'miscellaneous'],
-      ];
-
-      for (const [input, expected] of properties) {
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        assertEither(result, (data) => expect(aSingleDoc(data).outputDocPath).toContain(expected));
-      }
-    });
-
-    it('are placed in the slugified group folder if a group is provided', async () => {
-      const properties: [string, string][] = [
-        [
-          `/**
-           * @group MyGroup
-           */
-           public class MyClass {}`,
-          'mygroup',
-        ],
-        [
-          `/**
-           * @group MyGroup
-           */
-           public interface MyInterface {}`,
-          'mygroup',
-        ],
-        [
-          `/**
-           * @group MyGroup
-           */
-           public enum MyEnum {}`,
-          'mygroup',
-        ],
-      ];
-
-      for (const [input, expected] of properties) {
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        assertEither(result, (data) => expect(aSingleDoc(data).outputDocPath).toContain(expected));
-      }
-    });
-  });
-
-  describe('the generated bundles', () => {
-    it('return the type', async () => {
-      const properties: [string, string][] = [
-        ['public class MyClass {}', 'class'],
-        ['public interface MyInterface {}', 'interface'],
-        ['public enum MyEnum {}', 'enum'],
-      ];
-
-      for (const [input, expected] of properties) {
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-        assertEither(result, (data) => expect(aSingleDoc(data).source.type).toBe(expected));
-      }
-    });
-
-    it('do not return files out of scope', async () => {
-      const input1 = 'global class MyClass {}';
-      const input2 = 'public class AnotherClass {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
-        scope: ['global'],
-      })();
-      expect(result).documentationBundleHasLength(1);
-    });
-
-    it('do not return files that have an @ignore in the docs', async () => {
-      const input = `
-      /**
-        * @ignore
-        */
-      public class MyClass {}`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(0);
-    });
-  });
-
-  describe('the documentation content', () => {
-    it('includes a heading with the type name', async () => {
-      const properties: [string, string][] = [
-        ['public class MyClass {}', 'MyClass Class'],
-        ['public enum MyEnum {}', 'MyEnum Enum'],
-        ['public interface MyInterface {}', 'MyInterface Interface'],
-      ];
-
-      for (const [input, expected] of properties) {
-        const result = await generateDocs([apexBundleFromRawString(input)])();
-
-        expect(result).documentationBundleHasLength(1);
-        assertEither(result, (data) => expect(data).firstDocContains(expected));
-      }
-    });
-
-    it('displays type level annotations', async () => {
-      const input = `
-        @NamespaceAccessible
-        public class MyClass {
-          @Deprecated
-          public 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 metadata as annotations', async () => {
-      const input = 'public class MyClass {}';
-      const metadata = `
-        <?xml version="1.0" encoding="UTF-8"?>
-        <ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
-            <apiVersion>59.0</apiVersion>
-            <status>Active</status>
-        </ApexClass>
-        `;
-
-      const result = await generateDocs([apexBundleFromRawString(input, metadata)])();
-
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('APIVERSION'));
-      assertEither(result, (data) => expect(data).firstDocContains('STATUS'));
-    });
-
-    it('displays the description when no @description tag is used', async () => {
-      const input = `
-          /**
-           * This is a description
-           */
-          public class MyClass {}
-         `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
-    });
-
-    it('displays the description when a @description tag is used', async () => {
-      const input = `
-          /**
-            * @description This is a description
-            */
-          public class MyClass {}`;
-
-      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 class MyClass {}
-        `;
-
-      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 class MyClass {}`;
-
-      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 class MyClass {}`;
-
-      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 class MyClass {}`;
-
-      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 with links', async () => {
-      const input1 = `
-          /**
-            * @description This is a description with a {@link ClassRef} reference
-            */
-          public enum MyClass {}
-          `;
-
-      const input2 = 'public class ClassRef {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
-      expect(result).documentationBundleHasLength(2);
-      assertEither(result, (data) =>
-        expect(data).firstDocContains('This is a description with a [ClassRef](ClassRef.md) reference'),
-      );
-    });
-
-    it('displays descriptions with emails', async () => {
-      const input = `
-          /**
-            * @description This is a description with an {@email test@testerson.com} email
-            */
-          public class MyClass {}
-          `;
-
-      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 ClassRef
-            */
-          public class MyClass {}
-          `;
-
-      const input2 = 'public class ClassRef {}';
-
-      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('[ClassRef](ClassRef.md)'));
-    });
-
-    it('displays @sees without links when the reference is not found', async () => {
-      const input = `
-        /**
-          * @see ClassRef
-          */
-        public class MyClass {}
-        `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('See'));
-      assertEither(result, (data) => expect(data).firstDocContains('ClassRef'));
-    });
-
-    it('displays the namespace if present in the config', async () => {
-      const input = 'public class MyClass {}';
-
-      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 class MyClass {}';
-
-      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 class MyClass {}
-          `;
-
-      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 class MyClass {}`;
-
-      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('does not display tags marked as excluded', async () => {
-      const input = `
-        /**
-          * @see ClassRef
-          */
-        public class MyClass {}
-        `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], {
-        excludeTags: ['see'],
-      })();
-
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContainsNot('See'));
-    });
-  });
-});

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

@@ -1,61 +0,0 @@
-import { assertEither, extendExpect } from './expect-extensions';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-
-describe('Generates enum documentation', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  describe('documentation content', () => {
-    it('displays values', async () => {
-      const input = `
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Values'));
-      assertEither(result, (data) => expect(data).firstDocContains('VALUE1'));
-      assertEither(result, (data) => expect(data).firstDocContains('VALUE2'));
-    });
-
-    it('displays values sorted when sortAlphabetically is true', async () => {
-      const input = `
-      public enum MyEnum {
-        VALUE2,
-        VALUE1
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Values'));
-      assertEither(result, (data) => {
-        const value1Index = data.docs[0].content.indexOf('VALUE1');
-        const value2Index = data.docs[0].content.indexOf('VALUE2');
-        expect(value1Index).toBeLessThan(value2Index);
-      });
-    });
-
-    it('does not sort values when sortAlphabetically is false', async () => {
-      const input = `
-      public enum MyEnum {
-        VALUE2,
-        VALUE1
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data).firstDocContains('## Values'));
-      assertEither(result, (data) => {
-        const value1Index = data.docs[0].content.indexOf('VALUE1');
-        const value2Index = data.docs[0].content.indexOf('VALUE2');
-        expect(value1Index).toBeGreaterThan(value2Index);
-      });
-    });
-  });
-});

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

@@ -1,169 +0,0 @@
-import { assertEither, extendExpect } from './expect-extensions';
-import { apexBundleFromRawString, generateDocs } from './test-helpers';
-
-describe('Generates interface documentation', () => {
-  beforeAll(() => {
-    extendExpect();
-  });
-
-  describe('documentation content', () => {
-    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 sortAlphabetically is true', async () => {
-        const input = `
-        public interface MyInterface {
-          void myMethod();
-          void anotherMethod();
-        }
-      `;
-
-        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 sortAlphabetically is false', async () => {
-        const input = `
-        public interface MyInterface {
-          void myMethod();
-          void anotherMethod();
-        }
-      `;
-
-        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'));
-        });
-      });
-
-      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',
-          ),
-        );
-      });
-    });
-  });
-});