@cparra/apexdocs 2.25.0-alpha.0 → 2.25.0-alpha.2

package/src/__spec__/core/generating-interface-docs.spec.ts

@@ -0,0 +1,431 @@
+import { assertEither, extendExpect } from './expect-extensions';
+import { generateDocs } from '../../core/generate-docs';
+
+describe('Generates interface documentation', () => {
+  beforeAll(() => {
+    extendExpect();
+  });
+
+  describe('documentation output', () => {
+    it('always returns markdown as the format', () => {
+      const input = `
+      public interface MyInterface {
+      }
+     `;
+
+      const result = generateDocs([input]);
+      assertEither(result, (data) => expect(data.format).toBe('markdown'));
+    });
+
+    it('returns the name of the interface', () => {
+      const input = `
+      public interface MyInterface {
+      }
+      `;
+
+      const result = generateDocs([input]);
+      expect(result).documentationBundleHasLength(1);
+      assertEither(result, (data) => expect(data.docs[0].typeName).toBe('MyInterface'));
+    });
+
+    it('returns the type as interface', () => {
+      const input = `
+      public interface MyInterface {
+      }
+      `;
+
+      const result = generateDocs([input]);
+      expect(result).documentationBundleHasLength(1);
+      assertEither(result, (data) => expect(data.docs[0].type).toBe('interface'));
+    });
+
+    it('does not return interfaces out of scope', () => {
+      const input1 = `
+        global interface MyInterface {}
+      `;
+
+      const input2 = `
+        public interface AnotherInterface {}
+      `;
+
+      const result = generateDocs([input1, input2], { scope: ['global'] });
+      expect(result).documentationBundleHasLength(1);
+    });
+
+    it('does not return interfaces that have an @ignore in the docs', () => {
+      const input = `
+      /**
+        * @ignore
+        */
+      public interface MyInterface {}`;
+
+      const result = generateDocs([input]);
+      expect(result).documentationBundleHasLength(0);
+    });
+
+    it('does not return interface methods that have @ignore in the docs', () => {
+      const input = `
+      public interface MyInterface {
+        /**
+          * @ignore
+          */
+        void myMethod();
+      }`;
+
+      const result = generateDocs([input]);
+      expect(result).documentationBundleHasLength(1);
+      assertEither(result, (data) => expect(data.docs[0].docContents).not.toContain('myMethod'));
+    });
+  });
+
+  describe('documentation content', () => {
+    describe('type level information', () => {
+      it('generates a heading with the interface name', () => {
+        const input = `
+        public interface MyInterface {}
+      `;
+
+        const output = `# MyInterface Interface`;
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains(output));
+      });
+
+      it('displays type level annotations', () => {
+        const input = `
+        @NamespaceAccessible
+        public interface MyInterface {
+          @Deprecated
+          void myMethod();   
+        }
+       `;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('NAMESPACEACCESSIBLE'));
+        assertEither(result, (data) => expect(data).firstDocContains('DEPRECATED'));
+      });
+
+      it('displays the description', () => {
+        const input = `
+          /**
+           * This is a description
+           */
+          public interface MyInterface {}
+         `;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
+      });
+
+      it('display custom documentation tags', () => {
+        const input = `
+          /**
+           * @custom-tag My Value
+           */
+          public interface MyInterface {}
+        `;
+
+        const result = generateDocs([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', () => {
+        const input = `
+          /**
+           * @group MyGroup
+           */
+          public interface MyInterface {}`;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('Group'));
+        assertEither(result, (data) => expect(data).firstDocContains('MyGroup'));
+      });
+
+      it('displays the author', () => {
+        const input = `
+          /**
+           * @author John Doe
+           */
+          public interface MyInterface {}`;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('Author'));
+        assertEither(result, (data) => expect(data).firstDocContains('John Doe'));
+      });
+
+      it('displays the date', () => {
+        const input = `
+          /**
+           * @date 2021-01-01
+           */
+          public interface MyInterface {}`;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('Date'));
+        assertEither(result, (data) => expect(data).firstDocContains('2021-01-01'));
+      });
+
+      it('displays descriptions', () => {
+        const input = `
+          /**
+            * @description This is a description
+            */
+          public interface MyInterface {}`;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('This is a description'));
+      });
+
+      it('displays descriptions with links', () => {
+        const input1 = `
+          /**
+            * @description This is a description with a {@link InterfaceRef} reference
+            */
+          public enum MyInterface {}
+          `;
+
+        const input2 = 'public interface InterfaceRef {}';
+
+        const result = generateDocs([input1, 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', () => {
+        const input = `
+          /**
+            * @description This is a description with an {@email test@testerson.com} email
+            */
+          public interface MyInterface {}
+          `;
+
+        const result = generateDocs([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', () => {
+        const input1 = `
+          /**
+            * @see InterfaceRef
+            */
+          public interface MyInterface {}
+          `;
+
+        const input2 = 'public interface InterfaceRef {}';
+
+        const result = generateDocs([input1, 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', () => {
+        const input = `
+          /**
+            * @see InterfaceRef
+            */
+          public interface MyInterface {}
+          `;
+
+        const result = generateDocs([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', () => {
+        const input = 'public interface MyInterface {}';
+
+        const result = generateDocs([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', () => {
+        const input = 'public interface MyInterface {}';
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContainsNot('## Namespace'));
+      });
+
+      it('displays a mermaid diagram', () => {
+        const input = `
+          /**
+            * @mermaid
+            * graph TD
+            *   A[Square Rect] -- Link text --> B((Circle))
+            *   A --> C(Round Rect)
+            *   B --> D{Rhombus}
+            *   C --> D
+            */
+          public interface MyInterface {}
+          `;
+
+        const result = generateDocs([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', () => {
+        const input = `
+          /**
+            * @example
+            * public class MyClass {
+            *   public void myMethod() {
+            *     System.debug('Hello, World!');
+            *   }
+            * }
+            */
+          public interface MyInterface {}`;
+
+        const result = generateDocs([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', () => {
+        const input = `
+        public interface MyInterface {
+          void myMethod();
+        }
+      `;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('## Methods'));
+      });
+
+      it('supports having mermaid diagrams in method descriptions', () => {
+        const input = `
+        public interface MyInterface {
+          /**
+            * @mermaid
+            * graph TD
+            *   A[Square Rect] -- Link text --> B((Circle))
+            *   A --> C(Round Rect)
+            *   B --> D{Rhombus}
+            *   C --> D
+            */
+          void myMethod();
+        }
+      `;
+
+        const result = generateDocs([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', () => {
+        const input = `
+        public interface MyInterface {
+          /**
+            * @example
+            * public class MyClass {
+            *   public void myMethod() {
+            *     System.debug('Hello, World!');
+            *   }
+            * }
+            */
+          void myMethod();
+        }
+      `;
+
+        const result = generateDocs([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', () => {
+        const input = `
+        public interface MyInterface {
+          void myMethod();
+        }
+      `;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('### Signature'));
+      });
+
+      it('has a parameters section', () => {
+        const input = `
+        public interface MyInterface {
+          void myMethod(String param1, Integer param2);
+        }
+      `;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('### Parameters'));
+      });
+
+      it('has a return type section', () => {
+        const input = `
+        public interface MyInterface {
+          String myMethod();
+        }
+      `;
+
+        const result = generateDocs([input]);
+        expect(result).documentationBundleHasLength(1);
+        assertEither(result, (data) => expect(data).firstDocContains('### Return Type'));
+      });
+
+      it('has a throws section', () => {
+        const input = `
+        public interface MyInterface {
+          /**
+            * @throws MyException
+            */
+          void myMethod();
+        }
+      `;
+
+        const result = generateDocs([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', () => {
+        const input1 = `
+        public interface MyInterface {
+          void myMethod();
+        }
+      `;
+
+        const input2 = `
+        public interface AnotherInterface extends MyInterface {}
+      `;
+
+        const result = generateDocs([input1, input2]);
+        expect(result).documentationBundleHasLength(2);
+        assertEither(result, (data) =>
+          expect(data.docs.find((doc) => doc.typeName === 'AnotherInterface')?.docContents).toContain('Inherited'),
+        );
+      });
+    });
+  });
+});

package/src/__spec__/core/generating-reference-guide.spec.ts

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

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

@@ -3,28 +3,32 @@ import { AnnotationBuilder } from '../../test-helpers/AnnotationBuilder';
 import { MethodMirrorBuilder, ParameterBuilder } from '../../test-helpers/MethodMirrorBuilder';
 import { interfaceTypeToInterfaceSource } from '../apex-types';
 
+function linkGenerator(type: string): string {
+  return type;
+}
+
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {
   it('converts the name', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().withName('SampleInterface').build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
 
     expect(interfaceSource.name).toBe('SampleInterface');
   });
 
   it('converts the access modifier', () => {
     const interfaceMirror = new InterfaceMirrorBuilder().build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
 
-    expect(interfaceSource.accessModifier).toBe('public');
+    expect(interfaceSource.meta.accessModifier).toBe('public');
   });
 
   it('converts annotations', () => {
     const interfaceMirror = new InterfaceMirrorBuilder()
       .addAnnotation(new AnnotationBuilder().withName('MyAnnotation').build())
       .build();
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
 
-    expect(interfaceSource.annotations).toEqual(['MYANNOTATION']);
+    expect(interfaceSource.doc.annotations).toEqual(['MYANNOTATION']);
   });
 
   it('converts method declarations. Method with no parameters', () => {
@@ -40,10 +44,10 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
 
-    expect(interfaceSource.methods).toHaveLength(1);
-    expect(interfaceSource.methods![0].signature).toBe('public String sampleMethod()');
+    expect(interfaceSource.methods.value).toHaveLength(1);
+    expect(interfaceSource.methods.value[0].signature.value[0]).toBe('public String sampleMethod()');
   });
 
   it('converts method declarations. Method with parameters', () => {
@@ -68,9 +72,9 @@ describe('Conversion from InterfaceMirror to InterfaceSource understandable by t
       )
       .build();
 
-    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror);
+    const interfaceSource = interfaceTypeToInterfaceSource(interfaceMirror, linkGenerator);
 
-    expect(interfaceSource.methods).toHaveLength(1);
-    expect(interfaceSource.methods![0].signature).toBe('public String sampleMethod(String param1)');
+    expect(interfaceSource.methods.value).toHaveLength(1);
+    expect(interfaceSource.methods.value[0].signature.value[0]).toBe('public String sampleMethod(String param1)');
   });
 });

package/src/adapters/__tests__/references.spec.ts

@@ -1,5 +1,5 @@
 import { replaceInlineReferences } from '../references';
-import { Link } from '../../templating/types';
+import { Link } from '../../core/renderable/types';
 
 function getFileLink(typeName: string): Link {
   return {