@cparra/apexdocs 3.0.0-alpha.9 → 3.0.0-rc.0

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

@@ -1,139 +1,11 @@
 import { assertEither, extendExpect } from './expect-extensions';
 import { apexBundleFromRawString, generateDocs } from './test-helpers';
 
-describe('Generates interface documentation', () => {
+describe('When generating documentation for a class', () => {
   beforeAll(() => {
     extendExpect();
   });
 
-  describe('documentation output', () => {
-    it('returns the name of the class', async () => {
-      const input = 'public class MyClass {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyClass'));
-    });
-
-    it('returns the type as class', async () => {
-      const input = 'public class MyClass {}';
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].source.type).toBe('class'));
-    });
-
-    it('does not return classes 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('does not return classes that have an @ignore in the docs', async () => {
-      const input = `
-      /**
-        * @ignore
-        */
-      public class MyClass {}`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(0);
-    });
-
-    it('does not return class methods that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public void myMethod() {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myMethod'));
-    });
-
-    it('does not return class properties that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public String myProperty { get; set; }
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myProperty'));
-    });
-
-    it('does not return class fields that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public String myField;
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('myField'));
-    });
-
-    it('does not return class inner classes that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public class InnerClass {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('InnerClass'));
-    });
-
-    it('does not return class inner interfaces that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public interface InnerInterface {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('InnerInterface'));
-    });
-
-    it('does not return class inner enums that have @ignore in the docs', async () => {
-      const input = `
-      public class MyClass {
-        /**
-          * @ignore
-          */
-        public enum InnerEnum {}
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].content).not.toContain('InnerEnum'));
-    });
-  });
-
   describe('documentation content', () => {
     describe('type level information', () => {
       it('generates a heading with the class name', async () => {

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

@@ -0,0 +1,111 @@
+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));
+      }
+    });
+  });
+
+  describe('the generated bundle', () => {
+    it('does 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('does 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);
+    });
+  });
+});

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

@@ -6,70 +6,6 @@ describe('Generates enum documentation', () => {
     extendExpect();
   });
 
-  describe('documentation output', () => {
-    it('returns the name of the enum', async () => {
-      const input = `
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].outputDocPath).toContain('MyEnum'));
-    });
-
-    it('returns the type as enum', async () => {
-      const input = `
-     public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].source.type).toBe('enum'));
-    });
-
-    it('does not return enums out of scope', async () => {
-      const input1 = `
-     global enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-    `;
-
-      const input2 = `
-      public enum MyEnum {
-          VALUE1,
-          VALUE2
-        }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input1), apexBundleFromRawString(input2)], {
-        scope: ['global'],
-      })();
-      expect(result).documentationBundleHasLength(1);
-    });
-
-    it('does not return enums that have an @ignore in the docs', async () => {
-      const input = `
-      /**
-        * @ignore
-        */
-      public enum MyEnum {
-        VALUE1,
-        VALUE2
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(0);
-    });
-  });
-
   describe('documentation content', () => {
     it('generates a heading with the enum name', async () => {
       const input = `

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

@@ -6,70 +6,6 @@ describe('Generates interface documentation', () => {
     extendExpect();
   });
 
-  describe('documentation output', () => {
-    it('returns the name of the interface', async () => {
-      const input = `
-      public interface MyInterface {
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].source.name).toBe('MyInterface'));
-    });
-
-    it('returns the type as interface', async () => {
-      const input = `
-      public interface MyInterface {
-      }
-      `;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      assertEither(result, (data) => expect(data.docs[0].source.type).toBe('interface'));
-    });
-
-    it('does not return interfaces out of scope', async () => {
-      const input1 = `
-        global interface MyInterface {}
-      `;
-
-      const input2 = `
-        public interface AnotherInterface {}
-      `;
-
-      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', async () => {
-      const input = `
-      /**
-        * @ignore
-        */
-      public interface MyInterface {}`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(0);
-    });
-
-    it('does not return interface methods that have @ignore in the docs', async () => {
-      const input = `
-      public interface MyInterface {
-        /**
-          * @ignore
-          */
-        void myMethod();
-      }`;
-
-      const result = await generateDocs([apexBundleFromRawString(input)])();
-      expect(result).documentationBundleHasLength(1);
-      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', async () => {

package/src/core/markdown/adapters/documentables.ts

@@ -98,7 +98,6 @@ export function adaptDocumentable(
         .map((currentAnnotation) => currentAnnotation.body) ?? []
     );
   }
-
   return {
     ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
     annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),

package/src/core/markdown/generate-docs.ts

@@ -1,5 +1,4 @@
 import { pipe } from 'fp-ts/function';
-//import * as E from 'fp-ts/Either';
 import * as TE from 'fp-ts/TaskEither';
 import yaml from 'js-yaml';
 
@@ -20,8 +19,7 @@ import {
   ParsedFile,
 } from '../shared/types';
 import { parsedFilesToRenderableBundle } from './adapters/renderable-bundle';
-import { myPipeSeq /*reflectSourceCode*/ } from './reflection/reflect-source';
-//import { checkForReflectionErrors } from './reflection/error-handling';
+import { reflectBundles } from './reflection/reflect-source';
 import { addInheritanceChainToTypes } from './reflection/inheritance-chain-expanion';
 import { addInheritedMembersToTypes } from './reflection/inherited-member-expansion';
 import { convertToDocumentationBundle } from './adapters/renderable-to-page-data';
@@ -63,8 +61,7 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config: Markdown
 
   return pipe(
     apexBundles,
-    myPipeSeq,
-    //checkForReflectionErrors,
+    reflectBundles,
     TE.map(filterOutOfScope),
     TE.map(addInheritedMembersToTypes),
     TE.map(addInheritanceChainToTypes),