@cparra/apexdocs 3.0.0-beta.1 → 3.0.0

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

@@ -4,11 +4,27 @@ import * as E from 'fp-ts/Either';
 import { apexBundleFromRawString, generateDocs } from './test-helpers';
 import { ReferenceGuidePageData } from '../../shared/types';
 
-describe('Generates a Reference Guide', () => {
+describe('When generating the Reference Guide', () => {
   beforeAll(() => {
     extendExpect();
   });
 
+  it('contains the correct default title by default', async () => {
+    const result = await generateDocs([])();
+
+    assertEither(result, (data) =>
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('# Apex Reference Guide'),
+    );
+  });
+
+  it('allows for the reference guide title to be configured', async () => {
+    const result = await generateDocs([], { referenceGuideTitle: 'Custom Title' })();
+
+    assertEither(result, (data) =>
+      expect((data.referenceGuide as ReferenceGuidePageData).content).toContain('# Custom Title'),
+    );
+  });
+
   it('returns a reference guide with links to all other files', async () => {
     const input1 = `
       public enum MyEnum {

package/src/core/markdown/__test__/test-helpers.ts

@@ -15,9 +15,11 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config?: Partial
     targetDir: 'target',
     scope: ['global', 'public'],
     defaultGroupName: 'Miscellaneous',
-    sortMembersAlphabetically: true,
+    sortAlphabetically: false,
     referenceGuideTemplate: referenceGuideTemplate,
     linkingStrategy: 'relative',
+    excludeTags: [],
+    referenceGuideTitle: 'Apex Reference Guide',
     ...config,
   });
 }

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

@@ -14,8 +14,10 @@ const defaultMarkdownGeneratorConfig: MarkdownGeneratorConfig = {
   namespace: '',
   defaultGroupName: 'Miscellaneous',
   referenceGuideTemplate: '',
-  sortMembersAlphabetically: false,
+  sortAlphabetically: false,
   linkingStrategy: 'relative',
+  referenceGuideTitle: 'Apex Reference Guide',
+  excludeTags: [],
 };
 
 describe('Conversion from InterfaceMirror to InterfaceSource understandable by the templating engine', () => {

package/src/core/markdown/adapters/renderable-to-page-data.ts

@@ -5,15 +5,16 @@ import { CompilationRequest, Template } from '../templates/template';
 import { enumMarkdownTemplate } from '../templates/enum-template';
 import { interfaceMarkdownTemplate } from '../templates/interface-template';
 import { classMarkdownTemplate } from '../templates/class-template';
-import { defaults } from '../../../defaults';
+import { markdownDefaults } from '../../../defaults';
 
 export const convertToDocumentationBundle = (
+  referenceGuideTitle: string,
   referenceGuideTemplate: string,
   { referencesByGroup, renderables }: RenderableBundle,
 ): DocumentationBundle => ({
   referenceGuide: {
     frontmatter: null,
-    content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
+    content: referencesToReferenceGuideContent(referenceGuideTitle, referencesByGroup, referenceGuideTemplate),
     outputDocPath: 'index.md',
   },
   docs: renderables.map((renderable: Renderable) =>
@@ -22,6 +23,7 @@ export const convertToDocumentationBundle = (
 });
 
 function referencesToReferenceGuideContent(
+  referenceGuideTitle: string,
   references: { [key: string]: ReferenceGuideReference[] },
   template: string,
 ): string {
@@ -39,7 +41,7 @@ function referencesToReferenceGuideContent(
   return pipe(references, alphabetizeReferences, (references) =>
     compile({
       template: template,
-      source: references,
+      source: { referenceGuideTitle: referenceGuideTitle, references },
     }),
   );
 }
@@ -59,7 +61,7 @@ function renderableToPageData(referenceGuideReference: ReferenceGuideReference[]
       outputDocPath: reference!.reference.outputDocPath,
       frontmatter: null,
       content: docContents,
-      group: renderable.doc.group ?? defaults.defaultGroupName,
+      group: renderable.doc.group ?? markdownDefaults.defaultGroupName,
     };
   }
 

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

@@ -26,24 +26,16 @@ import { convertToDocumentationBundle } from './adapters/renderable-to-page-data
 import { filterScope } from './reflection/filter-scope';
 import { Template } from './templates/template';
 import { hookableTemplate } from './templates/hookable';
-import { sortMembers } from './reflection/sort-members';
+import { sortTypesAndMembers } from './reflection/sort-types-and-members';
 import { isSkip } from '../shared/utils';
 import { parsedFilesToReferenceGuide } from './adapters/reference-guide';
+import { removeExcludedTags } from './reflection/remove-excluded-tags';
 
-export type MarkdownGeneratorConfig = Pick<
+export type MarkdownGeneratorConfig = Omit<
   UserDefinedMarkdownConfig,
-  | 'targetDir'
-  | 'scope'
-  | 'namespace'
-  | 'defaultGroupName'
-  | 'transformReferenceGuide'
-  | 'transformDocs'
-  | 'transformDocPage'
-  | 'transformReference'
-  | 'linkingStrategy'
+  'sourceDir' | 'targetGenerator' | 'includeMetadata'
 > & {
   referenceGuideTemplate: string;
-  sortMembersAlphabetically: boolean;
 };
 
 export class HookError {
@@ -56,8 +48,13 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config: Markdown
   const filterOutOfScope = apply(filterScope, config.scope);
   const convertToReferences = apply(parsedFilesToReferenceGuide, config);
   const convertToRenderableBundle = apply(parsedFilesToRenderableBundle, config);
-  const convertToDocumentationBundleForTemplate = apply(convertToDocumentationBundle, config.referenceGuideTemplate);
-  const sortTypeMembers = apply(sortMembers, config.sortMembersAlphabetically);
+  const convertToDocumentationBundleForTemplate = apply(
+    convertToDocumentationBundle,
+    config.referenceGuideTitle,
+    config.referenceGuideTemplate,
+  );
+  const sort = apply(sortTypesAndMembers, config.sortAlphabetically);
+  const removeExcluded = apply(removeExcludedTags, config.excludeTags);
 
   return pipe(
     apexBundles,
@@ -65,7 +62,8 @@ export function generateDocs(apexBundles: UnparsedSourceFile[], config: Markdown
     TE.map(filterOutOfScope),
     TE.map(addInheritedMembersToTypes),
     TE.map(addInheritanceChainToTypes),
-    TE.map(sortTypeMembers),
+    TE.map(sort),
+    TE.map(removeExcluded),
     TE.bindTo('parsedFiles'),
     TE.bind('references', ({ parsedFiles }) => TE.right(convertToReferences(parsedFiles))),
     TE.flatMap(({ parsedFiles, references }) => transformReferenceHook(config)({ references, parsedFiles })),

package/src/core/markdown/reflection/__test__/filter-scope.spec.ts

@@ -0,0 +1,290 @@
+import { ClassMirror, EnumMirror, InterfaceMirror } from '@cparra/apex-reflection';
+import { filterScope } from '../filter-scope';
+import { parsedFileFromRawString } from './helpers';
+
+describe('When filtering scope', () => {
+  it('filters out files with the @ignore annotation', () => {
+    const properties: [string, number][] = [
+      [
+        `
+        /**
+         * @ignore
+         */
+        global class MyClass {}
+        `,
+        0,
+      ],
+      ['global class MyClass {}', 1],
+    ];
+
+    for (const [input, expected] of properties) {
+      const parsedFile = parsedFileFromRawString(input);
+
+      const result = filterScope(['global'], [parsedFile]);
+
+      expect(result).toHaveLength(expected);
+    }
+  });
+
+  describe('when scoping a class', () => {
+    it('filters out methods tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global void myMethod() {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global void myMethod() {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).methods).toHaveLength(expected);
+      }
+    });
+
+    it('filters out properties tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global Integer myProperty { get; set; }
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global Integer myProperty { get; set; }
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).properties).toHaveLength(expected);
+      }
+    });
+
+    it('filters out fields tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global Integer myField;
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global Integer myField;
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).fields).toHaveLength(expected);
+      }
+    });
+
+    it('filters out inner classes tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global class InnerClass {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global class InnerClass {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).classes).toHaveLength(expected);
+      }
+    });
+
+    it('filters out inner interfaces tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global interface InnerInterface {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global interface InnerInterface {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).interfaces).toHaveLength(expected);
+      }
+    });
+
+    it('filters out inner enums tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global class MyClass {
+            /**
+             * @ignore
+             */
+            global enum InnerEnum {}
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global class MyClass {
+            global enum InnerEnum {}
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as ClassMirror).enums).toHaveLength(expected);
+      }
+    });
+  });
+
+  describe('when scoping an interface', () => {
+    it('filters out methods tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global interface MyInterface {
+            /**
+             * @ignore
+             */
+            void myMethod();
+          }
+          `,
+          0,
+        ],
+        [
+          `
+          global interface MyInterface {
+            void myMethod();
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as InterfaceMirror).methods).toHaveLength(expected);
+      }
+    });
+  });
+
+  describe('when scoping an enum', () => {
+    it('never filters out enum values, even if tagged with @ignore', () => {
+      const properties: [string, number][] = [
+        [
+          `
+          global enum MyEnum {
+            /**
+             * @ignore
+             */
+            VALUE
+          }
+          `,
+          1,
+        ],
+        [
+          `
+          global enum MyEnum {
+            VALUE
+          }
+          `,
+          1,
+        ],
+      ];
+
+      for (const [input, expected] of properties) {
+        const parsedFile = parsedFileFromRawString(input);
+
+        const result = filterScope(['global'], [parsedFile]);
+
+        expect((result[0].type as EnumMirror).values).toHaveLength(expected);
+      }
+    });
+  });
+});

package/src/core/markdown/reflection/__test__/helpers.ts

@@ -0,0 +1,18 @@
+import { ParsedFile } from '../../../shared/types';
+import { reflect } from '@cparra/apex-reflection';
+
+export function parsedFileFromRawString(raw: string): ParsedFile {
+  const { error, typeMirror } = reflect(raw);
+  if (error) {
+    throw new Error(error.message);
+  }
+
+  return {
+    source: {
+      filePath: 'test.cls',
+      name: typeMirror!.name,
+      type: typeMirror!.type_name,
+    },
+    type: typeMirror!,
+  };
+}

package/src/core/markdown/reflection/__test__/remove-excluded-tags.spec.ts

@@ -0,0 +1,200 @@
+import { parsedFileFromRawString } from './helpers';
+import { removeExcludedTags } from '../remove-excluded-tags';
+import { ClassMirror, InterfaceMirror } from '@cparra/apex-reflection';
+
+describe('when removing excluded tags', () => {
+  describe('from any type', () => {
+    it('removes annotations', () => {
+      const tagsToExclude = ['group'];
+      const content = `
+        /**
+         * @group MyGroup
+         * @custom myCustomTag
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.annotations).toHaveLength(1);
+      expect(result[0].type.docComment?.annotations[0].name).toBe('custom');
+    });
+
+    it('removes example annotations', () => {
+      const tagsToExclude = ['example'];
+      const content = `
+        /**
+         * @example
+         * This is my example
+         * public void myMethod() {}
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.exampleAnnotation).toBeNull();
+    });
+
+    it('removes params annotations', () => {
+      const tagsToExclude = ['param'];
+      const content = `
+        /**
+         * @param myParam
+         * public void myMethod() {}
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.paramAnnotations).toHaveLength(0);
+    });
+
+    it('removes the return annotation', () => {
+      const tagsToExclude = ['return'];
+      const content = `
+        /**
+         * @return myReturn
+         * public void myMethod() {}
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.returnAnnotation).toBeNull();
+    });
+
+    it('removes the throws annotations', () => {
+      const tagsToExclude = ['throws'];
+      const content = `
+        /**
+         * @throws MyException
+         * public void myMethod() {}
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.throwsAnnotations).toHaveLength(0);
+    });
+
+    it('removes the exception annotations', () => {
+      const tagsToExclude = ['exception'];
+      const content = `
+        /**
+         * @exception MyException
+         * public void myMethod() {}
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.throwsAnnotations).toHaveLength(0);
+    });
+
+    it('removes descriptions', () => {
+      const tagsToExclude = ['description'];
+      const content = `
+        /**
+         * @description This is my description
+         * public void myMethod() {}
+         */
+        global class MyClass {}
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect(result[0].type.docComment?.description).toBe('');
+      expect(result[0].type.docComment?.descriptionLines).toHaveLength(0);
+    });
+  });
+
+  describe('from an interface', () => {
+    it('removes annotations from methods', () => {
+      const tagsToExclude = ['throws'];
+      const content = `
+        global interface MyInterface {
+          /**
+           * @throws MyException
+           */
+          void myMethod();
+        }
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      expect((result[0].type as InterfaceMirror).methods[0].docComment?.throwsAnnotations).toHaveLength(0);
+    });
+  });
+
+  describe('from a class', () => {
+    it('removes annotations from members', () => {
+      const tagsToExclude = ['throws'];
+      const content = `
+        global class MyClass {
+          /**
+           * @throws MyException
+           */
+          String myProperty {get; set;}
+          
+          /**
+           * @throws MyException
+           */
+          String myField;
+          /**
+           * @throws MyException
+           */
+          void myMethod() {}
+          
+          /**
+           * @throws MyException
+           */
+          MyClass() {}
+          
+          /**
+           * @throws MyException
+           */
+           public enum MyEnum {}
+           
+          /**
+            * @throws MyException
+            */
+          interface MyInnerInterface {}
+          
+          /**
+            * @throws MyException
+            */
+          class MyInnerClass {}
+        }
+        `;
+      const parsedFile = parsedFileFromRawString(content);
+
+      const result = removeExcludedTags(tagsToExclude, [parsedFile]);
+
+      const classMirror = result[0].type as ClassMirror;
+      expect(classMirror.methods[0].docComment?.throwsAnnotations).toHaveLength(0);
+      expect(classMirror.properties[0].docComment?.throwsAnnotations).toHaveLength(0);
+      expect(classMirror.fields[0].docComment?.throwsAnnotations).toHaveLength(0);
+      expect(classMirror.constructors[0].docComment?.throwsAnnotations).toHaveLength(0);
+      expect(classMirror.enums[0].docComment?.throwsAnnotations).toHaveLength(0);
+      expect(classMirror.interfaces[0].docComment?.throwsAnnotations).toHaveLength(0);
+      expect(classMirror.classes[0].docComment?.throwsAnnotations).toHaveLength(0);
+    });
+  });
+});
+
+// fields
+// inner interfaces
+// inner classes