@cparra/apexdocs 3.0.0-rc.0 → 3.0.0

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

@@ -6,251 +6,6 @@ describe('When generating documentation for a class', () => {
     extendExpect();
   });
 
-  describe('documentation content', () => {
-    describe('type level information', () => {
-      it('generates a heading with the class name', async () => {
-        const input = 'public class MyClass {}';
-
-        const output = `# MyClass Class`;
-        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 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', 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('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', 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('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'));
-      });
-    });
-  });
-
   describe('member information', () => {
     it('displays the Method heading', async () => {
       const input = `
@@ -272,7 +27,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aMethodIndex = data.docs[0].content.indexOf('aMethod');
@@ -289,7 +44,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aMethodIndex = data.docs[0].content.indexOf('aMethod');
@@ -318,7 +73,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aPropertyIndex = data.docs[0].content.indexOf('aProperty');
@@ -335,7 +90,7 @@ describe('When generating documentation for a class', () => {
         }  
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aPropertyIndex = data.docs[0].content.indexOf('aProperty');
@@ -364,7 +119,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aFieldIndex = data.docs[0].content.indexOf('aField');
@@ -381,7 +136,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aFieldIndex = data.docs[0].content.indexOf('aField');
@@ -422,7 +177,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aInnerClassIndex = data.docs[0].content.indexOf('AInnerClass');
@@ -439,7 +194,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aInnerClassIndex = data.docs[0].content.indexOf('AInnerClass');
@@ -468,7 +223,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aInnerInterfaceIndex = data.docs[0].content.indexOf('AInnerInterface');
@@ -485,7 +240,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aInnerInterfaceIndex = data.docs[0].content.indexOf('AInnerInterface');
@@ -514,7 +269,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: true })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: true })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aInnerEnumIndex = data.docs[0].content.indexOf('AInnerEnum');
@@ -531,7 +286,7 @@ describe('When generating documentation for a class', () => {
         }
       `;
 
-      const result = await generateDocs([apexBundleFromRawString(input)], { sortMembersAlphabetically: false })();
+      const result = await generateDocs([apexBundleFromRawString(input)], { sortAlphabetically: false })();
       expect(result).documentationBundleHasLength(1);
       assertEither(result, (data) => {
         const aInnerEnumIndex = data.docs[0].content.indexOf('AInnerEnum');
@@ -603,3 +358,5 @@ describe('When generating documentation for a class', () => {
     });
   });
 });
+
+// TODO: Skips tags at the member level

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

@@ -84,10 +84,8 @@ describe('When generating documentation', () => {
         assertEither(result, (data) => expect(aSingleDoc(data).source.type).toBe(expected));
       }
     });
-  });
 
-  describe('the generated bundle', () => {
-    it('does not return files out of scope', async () => {
+    it('do not return files out of scope', async () => {
       const input1 = 'global class MyClass {}';
       const input2 = 'public class AnotherClass {}';
 
@@ -97,7 +95,7 @@ describe('When generating documentation', () => {
       expect(result).documentationBundleHasLength(1);
     });
 
-    it('does not return files that have an @ignore in the docs', async () => {
+    it('do not return files that have an @ignore in the docs', async () => {
       const input = `
       /**
         * @ignore
@@ -108,4 +106,273 @@ describe('When generating documentation', () => {
       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'));
+    });
+  });
 });