@cparra/apexdocs 2.25.0-alpha.3 → 2.25.0-alpha.5

package/src/{__spec__/core → core/markdown/__test__}/generating-interface-docs.spec.ts

@@ -1,6 +1,5 @@
 import { assertEither, extendExpect } from './expect-extensions';
-import { generateDocs } from '../../core/generate-docs';
-import { apexBundleFromRawString } from './test-helpers';
+import { apexBundleFromRawString, generateDocs } from './test-helpers';
 
 describe('Generates interface documentation', () => {
   beforeAll(() => {
@@ -8,39 +7,29 @@ describe('Generates interface documentation', () => {
   });
 
   describe('documentation output', () => {
-    it('always returns markdown as the format', () => {
-      const input = `
-      public interface MyInterface {
-      }
-     `;
-
-      const result = generateDocs([apexBundleFromRawString(input)]);
-      assertEither(result, (data) => expect(data.format).toBe('markdown'));
-    });
-
-    it('returns the name of the interface', () => {
+    it('returns the name of the interface', async () => {
       const input = `
       public interface MyInterface {
       }
       `;
 
-      const result = generateDocs([apexBundleFromRawString(input)]);
+      const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].typeName).toBe('MyInterface'));
+      assertEither(result, (data) => expect(data.docs[0].source.name).toBe('MyInterface'));
     });
 
-    it('returns the type as interface', () => {
+    it('returns the type as interface', async () => {
       const input = `
       public interface MyInterface {
       }
       `;
 
-      const result = generateDocs([apexBundleFromRawString(input)]);
+      const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].type).toBe('interface'));
+      assertEither(result, (data) => expect(data.docs[0].source.type).toBe('interface'));
     });
 
-    it('does not return interfaces out of scope', () => {
+    it('does not return interfaces out of scope', async () => {
       const input1 = `
         global interface MyInterface {}
       `;
@@ -49,24 +38,24 @@ describe('Generates interface documentation', () => {
         public interface AnotherInterface {}
       `;
 
-      const result = generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
+      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
         scope: ['global'],
-      });
+      })();
       expect(result).documentationBundleHasLength(1);
     });
 
-    it('does not return interfaces that have an @ignore in the docs', () => {
+    it('does not return interfaces that have an @ignore in the docs', async () => {
       const input = `
       /**
         * @ignore
         */
       public interface MyInterface {}`;
 
-      const result = generateDocs([apexBundleFromRawString(input)]);
+      const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(0);
     });
 
-    it('does not return interface methods that have @ignore in the docs', () => {
+    it('does not return interface methods that have @ignore in the docs', async () => {
       const input = `
       public interface MyInterface {
         /**
@@ -75,26 +64,26 @@ describe('Generates interface documentation', () => {
         void myMethod();
       }`;
 
-      const result = generateDocs([apexBundleFromRawString(input)]);
+      const result = await generateDocs([apexBundleFromRawString(input)])();
       expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].docContents).not.toContain('myMethod'));
+      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myMethod'));
     });
   });
 
   describe('documentation content', () => {
     describe('type level information', () => {
-      it('generates a heading with the interface name', () => {
+      it('generates a heading with the interface name', async () => {
         const input = `
         public interface MyInterface {}
       `;
 
         const output = `# MyInterface Interface`;
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => expect(data).firstDocContains(output));
       });
 
-      it('displays type level annotations', () => {
+      it('displays type level annotations', async () => {
         const input = `
         @NamespaceAccessible
         public interface MyInterface {
@@ -103,13 +92,13 @@ describe('Generates interface documentation', () => {
         }
        `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays the description', async () => {
         const input = `
           /**
            * This is a description
@@ -117,12 +106,12 @@ describe('Generates interface documentation', () => {
           public interface MyInterface {}
          `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('display custom documentation tags', async () => {
         const input = `
           /**
            * @custom-tag My Value
@@ -130,64 +119,64 @@ describe('Generates interface documentation', () => {
           public interface MyInterface {}
         `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays the group', async () => {
         const input = `
           /**
            * @group MyGroup
            */
           public interface MyInterface {}`;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays the author', async () => {
         const input = `
           /**
            * @author John Doe
            */
           public interface MyInterface {}`;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays the date', async () => {
         const input = `
           /**
            * @date 2021-01-01
            */
           public interface MyInterface {}`;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays descriptions', async () => {
         const input = `
           /**
             * @description This is a description
             */
           public interface MyInterface {}`;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays descriptions with links', async () => {
         const input1 = `
           /**
             * @description This is a description with a {@link InterfaceRef} reference
@@ -197,14 +186,14 @@ describe('Generates interface documentation', () => {
 
         const input2 = 'public interface InterfaceRef {}';
 
-        const result = generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)]);
+        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', () => {
+      it('displays descriptions with emails', async () => {
         const input = `
           /**
             * @description This is a description with an {@email test@testerson.com} email
@@ -212,7 +201,7 @@ describe('Generates interface documentation', () => {
           public interface MyInterface {}
           `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) =>
           expect(data).firstDocContains(
@@ -221,7 +210,7 @@ describe('Generates interface documentation', () => {
         );
       });
 
-      it('displays sees with accurately resolved links', () => {
+      it('displays sees with accurately resolved links', async () => {
         const input1 = `
           /**
             * @see InterfaceRef
@@ -231,13 +220,13 @@ describe('Generates interface documentation', () => {
 
         const input2 = 'public interface InterfaceRef {}';
 
-        const result = generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)]);
+        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', () => {
+      it('displays sees without links when the reference is not found', async () => {
         const input = `
           /**
             * @see InterfaceRef
@@ -245,30 +234,30 @@ describe('Generates interface documentation', () => {
           public interface MyInterface {}
           `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays the namespace if present in the config', async () => {
         const input = 'public interface MyInterface {}';
 
-        const result = generateDocs([apexBundleFromRawString(input)], { namespace: 'MyNamespace' });
+        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', () => {
+      it('does not display the namespace if not present in the config', async () => {
         const input = 'public interface MyInterface {}';
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => expect(data).firstDocContainsNot('## Namespace'));
       });
 
-      it('displays a mermaid diagram', () => {
+      it('displays a mermaid diagram', async () => {
         const input = `
           /**
             * @mermaid
@@ -281,13 +270,13 @@ describe('Generates interface documentation', () => {
           public interface MyInterface {}
           `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays an example code block', async () => {
         const input = `
           /**
             * @example
@@ -299,7 +288,7 @@ describe('Generates interface documentation', () => {
             */
           public interface MyInterface {}`;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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'));
@@ -307,19 +296,49 @@ describe('Generates interface documentation', () => {
     });
 
     describe('method information', () => {
-      it('displays the Method heading', () => {
+      it('displays the Method heading', async () => {
         const input = `
         public interface MyInterface {
           void myMethod();
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => expect(data).firstDocContains('## Methods'));
       });
 
-      it('supports having mermaid diagrams in method descriptions', () => {
+      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 {
           /**
@@ -334,13 +353,13 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('supports having example code blocks in method descriptions', async () => {
         const input = `
         public interface MyInterface {
           /**
@@ -355,49 +374,49 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('has a signature section', async () => {
         const input = `
         public interface MyInterface {
           void myMethod();
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => expect(data).firstDocContains('### Signature'));
       });
 
-      it('has a parameters section', () => {
+      it('has a parameters section', async () => {
         const input = `
         public interface MyInterface {
           void myMethod(String param1, Integer param2);
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => expect(data).firstDocContains('### Parameters'));
       });
 
-      it('has a return type section', () => {
+      it('has a return type section', async () => {
         const input = `
         public interface MyInterface {
           String myMethod();
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        const result = await generateDocs([apexBundleFromRawString(input)])();
         expect(result).documentationBundleHasLength(1);
         assertEither(result, (data) => expect(data).firstDocContains('### Return Type'));
       });
 
-      it('has a throws section', () => {
+      it('has a throws section', async () => {
         const input = `
         public interface MyInterface {
           /**
@@ -407,12 +426,12 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input)]);
+        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', () => {
+      it('displays an "inherited" tag if the method was inherited from a different interface', async () => {
         const input1 = `
         public interface MyInterface {
           void myMethod();
@@ -423,10 +442,10 @@ describe('Generates interface documentation', () => {
         public interface AnotherInterface extends MyInterface {}
       `;
 
-        const result = generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)]);
+        const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)])();
         expect(result).documentationBundleHasLength(2);
         assertEither(result, (data) =>
-          expect(data.docs.find((doc) => doc.typeName === 'AnotherInterface')?.docContents).toContain('Inherited'),
+          expect(data.docs.find((doc) => doc.fileName === 'AnotherInterface')?.content).toContain('Inherited'),
         );
       });
     });

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

@@ -0,0 +1,184 @@
+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/{__test__ → markdown/__test__}/inheritance-chain.test.ts

@@ -1,5 +1,5 @@
-import { ClassMirrorBuilder } from '../../test-helpers/ClassMirrorBuilder';
-import { createInheritanceChain } from '../inheritance-chain';
+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', () => {