@cparra/apexdocs 3.0.0-beta.1 → 3.0.0-rc.0

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/reflection/__test__/filter-scope.spec.ts

@@ -0,0 +1,306 @@
+import { ParsedFile } from '../../../shared/types';
+import { ClassMirror, EnumMirror, InterfaceMirror, reflect } from '@cparra/apex-reflection';
+import { filterScope } from '../filter-scope';
+
+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!,
+  };
+}
+
+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/shared/types.d.ts

@@ -1,17 +1,5 @@
 import { Type } from '@cparra/apex-reflection';
 
-export type Generator = 'markdown' | 'openapi';
-
-/**
- * The configurable hooks that can be used to modify the output of the generator.
- */
-export type ConfigurableHooks = {
-  transformReferenceGuide: TransformReferenceGuide;
-  transformDocs: TransformDocs;
-  transformDocPage: TransformDocPage;
-  transformReference: TransformReference;
-};
-
 type LinkingStrategy =
   // Links will be generated using relative paths.
   | 'relative'
@@ -24,8 +12,8 @@ type LinkingStrategy =
   | 'none';
 
 export type UserDefinedMarkdownConfig = {
-  targetGenerator: 'markdown';
   sourceDir: string;
+  targetGenerator: 'markdown';
   targetDir: string;
   scope: string[];
   defaultGroupName: string;
@@ -115,11 +103,21 @@ export type PostHookDocumentationBundle = {
   docs: DocPageData[];
 };
 
-// Configurable Hooks
+// CONFIGURABLE HOOKS
+
+/**
+ * The configurable hooks that can be used to modify the output of the generator.
+ */
+export type ConfigurableHooks = {
+  transformReferenceGuide: TransformReferenceGuide;
+  transformDocs: TransformDocs;
+  transformDocPage: TransformDocPage;
+  transformReference: TransformReference;
+};
 
-type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
+export type ConfigurableDocPageReference = Omit<DocPageReference, 'source'>;
 
-type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
+export type ConfigurableDocPageData = Omit<DocPageData, 'source' | 'outputDocPath'>;
 
 /**
  * Allows changing where the files are written to.

package/src/index.ts

@@ -1,4 +1,3 @@
-import { SetOptional } from 'type-fest';
 import type {
   ConfigurableHooks,
   Skip,
@@ -6,18 +5,18 @@ import type {
   ReferenceGuidePageData,
   DocPageData,
   DocPageReference,
+  ConfigurableDocPageData,
+  TransformReferenceGuide,
+  TransformDocs,
+  TransformDocPage,
+  TransformReference,
+  ConfigurableDocPageReference,
 } from './core/shared/types';
 import { defaults } from './defaults';
 
-type ConfigurableMarkdownConfig = Omit<
-  SetOptional<
-    UserDefinedMarkdownConfig,
-    'targetDir' | 'scope' | 'defaultGroupName' | 'includeMetadata' | 'sortMembersAlphabetically' | 'linkingStrategy'
-  >,
-  'targetGenerator'
->;
+type ConfigurableMarkdownConfig = Omit<Partial<UserDefinedMarkdownConfig>, 'targetGenerator'>;
 
-function defineMarkdownConfig(config: ConfigurableMarkdownConfig): UserDefinedMarkdownConfig {
+function defineMarkdownConfig(config: ConfigurableMarkdownConfig): Partial<UserDefinedMarkdownConfig> {
   return {
     ...defaults,
     ...config,
@@ -33,4 +32,18 @@ function skip(): Skip {
 
 // Exports
 
-export { defineMarkdownConfig, skip, ConfigurableHooks, ReferenceGuidePageData, DocPageData, DocPageReference };
+export {
+  defineMarkdownConfig,
+  skip,
+  TransformReferenceGuide,
+  TransformDocs,
+  TransformDocPage,
+  TransformReference,
+  ConfigurableHooks,
+  ReferenceGuidePageData,
+  DocPageData,
+  DocPageReference,
+  Skip,
+  ConfigurableDocPageData,
+  ConfigurableDocPageReference,
+};