@cparra/apexdocs 3.0.0-beta.1 → 3.0.0

package/src/cli/args.ts

@@ -1,10 +1,14 @@
 import { cosmiconfig, CosmiconfigResult } from 'cosmiconfig';
 import * as yargs from 'yargs';
-import { UserDefinedMarkdownConfig } from '../core/shared/types';
+import { UserDefinedConfig, UserDefinedMarkdownConfig } from '../core/shared/types';
 import { TypeScriptLoader } from 'cosmiconfig-typescript-loader';
 import { markdownOptions } from './commands/markdown';
 import { openApiOptions } from './commands/openapi';
 
+const configOnlyDefaults: Partial<UserDefinedMarkdownConfig> = {
+  excludeTags: [],
+};
+
 /**
  * Extracts configuration from a configuration file or the package.json
  * through cosmiconfig.
@@ -37,10 +41,15 @@ function _extractYargs(config?: CosmiconfigResult) {
 /**
  * Combines the extracted configuration and arguments.
  */
-export async function extractArgs(): Promise<UserDefinedMarkdownConfig> {
+export async function extractArgs(): Promise<UserDefinedConfig> {
   const config = await _extractConfig();
   const cliArgs = _extractYargs(config);
   const commandName = cliArgs._[0];
 
-  return { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
+  const mergedConfig = { ...config?.config, ...cliArgs, targetGenerator: commandName as 'markdown' | 'openapi' };
+  if (mergedConfig.targetGenerator === 'markdown') {
+    return { ...configOnlyDefaults, ...mergedConfig };
+  } else {
+    return mergedConfig;
+  }
 }

package/src/cli/commands/markdown.ts

@@ -1,5 +1,5 @@
 import { Options } from 'yargs';
-import { defaults } from '../../defaults';
+import { markdownDefaults } from '../../defaults';
 
 export const markdownOptions: { [key: string]: Options } = {
   sourceDir: {
@@ -11,43 +11,46 @@ export const markdownOptions: { [key: string]: Options } = {
   targetDir: {
     type: 'string',
     alias: 't',
-    default: defaults.targetDir,
+    default: markdownDefaults.targetDir,
     describe: 'The directory location where documentation will be generated to.',
   },
   scope: {
     type: 'string',
     array: true,
     alias: 'p',
-    default: defaults.scope,
+    default: markdownDefaults.scope,
     describe:
       'A list of scopes to document. Values should be separated by a space, e.g --scope global public namespaceaccessible. ' +
       'Annotations are supported and should be passed lowercased and without the @ symbol, e.g. namespaceaccessible auraenabled.',
   },
   defaultGroupName: {
     type: 'string',
-    default: defaults.defaultGroupName,
+    default: markdownDefaults.defaultGroupName,
     describe: 'Defines the @group name to be used when a file does not specify it.',
   },
   namespace: {
     type: 'string',
-    describe:
-      'The package namespace, if any. If this value is provided the namespace will be added as a prefix to all of the parsed files. ' +
-      "If generating an OpenApi definition, it will be added to the file's Server Url.",
+    describe: 'The package namespace, if any. If provided, it will be added to the generated files.',
   },
-  sortMembersAlphabetically: {
+  sortAlphabetically: {
     type: 'boolean',
-    describe: 'Whether to sort members alphabetically.',
-    default: defaults.sortMembersAlphabetically,
+    describe: 'Whether to sort files and members alphabetically.',
+    default: markdownDefaults.sortAlphabetically,
   },
   includeMetadata: {
     type: 'boolean',
     describe: "Whether to include the file's meta.xml information: Whether it is active and and the API version",
-    default: defaults.includeMetadata,
+    default: markdownDefaults.includeMetadata,
   },
   linkingStrategy: {
     type: 'string',
     describe: 'The strategy to use when linking to other documentation pages.',
     choices: ['relative', 'no-link', 'none'],
-    default: defaults.linkingStrategy,
+    default: markdownDefaults.linkingStrategy,
+  },
+  referenceGuideTitle: {
+    type: 'string',
+    describe: 'The title of the reference guide.',
+    default: markdownDefaults.referenceGuideTitle,
   },
 };

package/src/cli/commands/openapi.ts

@@ -1,5 +1,5 @@
 import { Options } from 'yargs';
-import { defaults } from '../../defaults';
+import { markdownDefaults, openApiDefaults } from '../../defaults';
 
 export const openApiOptions: { [key: string]: Options } = {
   sourceDir: {
@@ -11,12 +11,12 @@ export const openApiOptions: { [key: string]: Options } = {
   targetDir: {
     type: 'string',
     alias: 't',
-    default: defaults.targetDir,
+    default: markdownDefaults.targetDir,
     describe: 'The directory location where the OpenApi file will be generated.',
   },
   fileName: {
     type: 'string',
-    default: 'openapi',
+    default: openApiDefaults.fileName,
     describe: 'The name of the OpenApi file to be generated.',
   },
   namespace: {
@@ -25,12 +25,12 @@ export const openApiOptions: { [key: string]: Options } = {
   },
   title: {
     type: 'string',
-    default: 'Apex REST API',
+    default: openApiDefaults.title,
     describe: 'The title of the OpenApi file.',
   },
   apiVersion: {
     type: 'string',
-    default: '1.0.0',
+    default: openApiDefaults.apiVersion,
     describe: 'The version of the OpenApi file.',
   },
 };

package/src/cli/generate.ts

@@ -1,16 +1,32 @@
 #!/usr/bin/env node
 import { Apexdocs } from '../application/Apexdocs';
 import { extractArgs } from './args';
+import { StdOutLogger } from '#utils/logger';
+import * as E from 'fp-ts/Either';
+
+const logger = new StdOutLogger();
 
 function main() {
-  function catchError(error: Error) {
-    console.error(error);
+  function parseResult(result: E.Either<unknown, string>) {
+    E.match(
+      (error) => {
+        logger.error(`❌ An error occurred while generating the documentation: ${error}`);
+        process.exit(1);
+      },
+      (successMessage: string) => {
+        logger.logSingle(successMessage);
+      },
+    )(result);
+  }
+
+  function catchUnexpectedError(error: Error) {
+    logger.error(`❌ An unexpected error occurred: ${error.message}`);
     process.exit(1);
   }
 
   extractArgs()
-    .then((config) => Apexdocs.generate(config).catch(catchError))
-    .catch(catchError);
+    .then((config) => Apexdocs.generate(config, logger).then(parseResult))
+    .catch(catchUnexpectedError);
 }
 
 main();

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

@@ -1,384 +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 () => {
-        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 = `
@@ -400,7 +27,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -417,7 +44,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -446,7 +73,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -463,7 +90,7 @@ describe('Generates interface documentation', () => {
         }  
       `;
 
-      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');
@@ -492,7 +119,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -509,7 +136,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -550,7 +177,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -567,7 +194,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -596,7 +223,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -613,7 +240,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -642,7 +269,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -659,7 +286,7 @@ describe('Generates interface documentation', () => {
         }
       `;
 
-      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');
@@ -731,3 +358,5 @@ describe('Generates interface documentation', () => {
     });
   });
 });
+
+// TODO: Skips tags at the member level