@cparra/apexdocs 2.25.0-alpha.4 → 2.25.0-alpha.5

package/src/cli/commands/markdown.ts

@@ -0,0 +1,58 @@
+import { Options } from 'yargs';
+import { defaults } from '../../defaults';
+
+export const markdownOptions: { [key: string]: Options } = {
+  sourceDir: {
+    type: 'string',
+    alias: 's',
+    demandOption: true,
+    describe: 'The directory location which contains your apex .cls classes.',
+  },
+  targetDir: {
+    type: 'string',
+    alias: 't',
+    default: defaults.targetDir,
+    describe: 'The directory location where documentation will be generated to.',
+  },
+  scope: {
+    type: 'string',
+    array: true,
+    alias: 'p',
+    default: defaults.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. ' +
+      'Note that this setting is ignored if generating an OpenApi REST specification since that looks for classes annotated with @RestResource.',
+  },
+  defaultGroupName: {
+    type: 'string',
+    default: defaults.defaultGroupName,
+    describe: 'Defines the @group name to be used when a file does not specify it.',
+  },
+  openApiTitle: {
+    type: 'string',
+    default: 'Apex REST Api',
+    describe: 'If using "openapi" as the target generator, this allows you to specify the OpenApi title value.',
+  },
+  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.",
+  },
+  openApiFileName: {
+    type: 'string',
+    describe: 'If using "openapi" as the target generator, this allows you to specify the name of the output file.',
+    default: 'openapi',
+  },
+  sortMembersAlphabetically: {
+    type: 'boolean',
+    describe: 'Whether to sort members alphabetically.',
+    default: defaults.sortMembersAlphabetically,
+  },
+  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,
+  },
+};

package/src/cli/generate.ts

@@ -3,12 +3,14 @@ import { Apexdocs } from '../application/Apexdocs';
 import { extractArgs } from './args';
 
 function main() {
+  function cathError(error: Error) {
+    console.error(error);
+    process.exit(1);
+  }
+
   extractArgs()
-    .then((config) => Apexdocs.generate(config))
-    .catch((error) => {
-      console.error(error);
-      process.exit(1);
-    });
+    .then((config) => Apexdocs.generate(config).catch(cathError))
+    .catch(cathError);
 }
 
 main();

package/src/{model/__tests__ → core/__test__}/manifest.spec.ts

@@ -1,4 +1,4 @@
-import Manifest from '../../core/manifest';
+import Manifest from '../manifest';
 import { EnumMirror } from '@cparra/apex-reflection';
 
 const sampleEnum: EnumMirror = {

package/src/core/manifest.ts

@@ -1,11 +1,11 @@
 import {
+  Annotation,
   ClassMirror,
+  DocComment,
+  DocCommentAnnotation,
   EnumMirror,
   InterfaceMirror,
   Type,
-  Annotation,
-  DocComment,
-  DocCommentAnnotation,
 } from '@cparra/apex-reflection';
 
 type AccessAndDocAware = { access_modifier: string; annotations: Annotation[]; docComment?: DocComment };
@@ -19,66 +19,72 @@ export default class Manifest {
    * @param types List of types to be wrapped by this object.
    * @param isForInnerTypes Whether this manifest represent an inner type or not.
    */
-  constructor(public types: Type[], public isForInnerTypes: boolean = false) {}
+  constructor(
+    public types: Type[],
+    public isForInnerTypes: boolean = false,
+  ) {}
 
   filteredByAccessModifierAndAnnotations(modifiers: string[]): Type[] {
-    const filteredTypes = this.filterAccessibleModifier(this.types, modifiers);
+    const filteredTypes = Manifest.filterAccessibleModifier(this.types, modifiers);
     const typesToReturn: Type[] = [];
     for (const filteredType of filteredTypes) {
-      const currentType = filteredType as Type;
-      if (currentType.type_name === 'enum') {
-        // Ignoring enum values is not supported.
-        typesToReturn.push(currentType);
-        continue;
-      }
+      typesToReturn.push(Manifest.filterSingleType(filteredType, modifiers, this.isForInnerTypes));
+    }
+
+    return typesToReturn;
+  }
 
-      if (currentType.type_name === 'interface') {
-        const currentInterface = currentType as InterfaceMirror;
-        typesToReturn.push({
-          ...currentType,
-          methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
-        } as InterfaceMirror);
-        continue;
-      }
+  static filterSingleType(currentType: Type, modifiers: string[], isForInnerTypes: boolean): Type {
+    if (currentType.type_name === 'enum') {
+      // Ignoring enum values is not supported.
+      return currentType;
+    }
 
-      const currentClass = currentType as ClassMirror;
-      let filteredClass = {
+    if (currentType.type_name === 'interface') {
+      const currentInterface = currentType as InterfaceMirror;
+      return {
         ...currentType,
-        methods: this.filterAccessibleModifier(currentClass.methods, modifiers),
-        properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
-        fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
-        constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
-      } as ClassMirror;
+        methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
+      } as InterfaceMirror;
+    }
 
-      if (!this.isForInnerTypes) {
-        filteredClass = {
-          ...filteredClass,
-          enums: this.filterAccessibleModifier(currentClass.enums, modifiers) as EnumMirror[],
-          interfaces: this.filterAccessibleModifier(currentClass.interfaces, modifiers) as InterfaceMirror[],
-          classes: new Manifest(currentClass.classes, true).filteredByAccessModifierAndAnnotations(
-            modifiers,
-          ) as ClassMirror[],
-        };
-      }
+    const currentClass = currentType as ClassMirror;
+    const filteredClass = {
+      ...currentType,
+      methods: this.filterAccessibleModifier(currentClass.methods, modifiers),
+      properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
+      fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
+      constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
+    } as ClassMirror;
 
-      typesToReturn.push(filteredClass);
+    if (!isForInnerTypes) {
+      return {
+        ...filteredClass,
+        enums: this.filterAccessibleModifier(currentClass.enums, modifiers) as EnumMirror[],
+        interfaces: this.filterAccessibleModifier(currentClass.interfaces, modifiers) as InterfaceMirror[],
+        classes: new Manifest(currentClass.classes, true).filteredByAccessModifierAndAnnotations(
+          modifiers,
+        ) as ClassMirror[],
+      };
     }
 
-    return typesToReturn;
+    return filteredClass;
+  }
+
+  static filterAccessibleModifier<T extends AccessAndDocAware>(accessAndDocAware: T[], modifiers: string[]): T[] {
+    return accessAndDocAware.filter((type) => this.shouldFilterType(type, modifiers));
   }
 
-  filterAccessibleModifier(accessAndDocAware: AccessAndDocAware[], modifiers: string[]) {
-    return accessAndDocAware.filter((currentType) => {
-      const hasIgnoreDocAnnotation = currentType.docComment?.annotations.some(
-        (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
-      );
-      if (hasIgnoreDocAnnotation) {
-        return false;
-      }
-      return (
-        modifiers.includes(currentType.access_modifier) ||
-        currentType.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
-      );
-    });
+  static shouldFilterType(accessAndDocAware: AccessAndDocAware, modifiers: string[]) {
+    const hasIgnoreDocAnnotation = accessAndDocAware.docComment?.annotations.some(
+      (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
+    );
+    if (hasIgnoreDocAnnotation) {
+      return false;
+    }
+    return (
+      modifiers.includes(accessAndDocAware.access_modifier) ||
+      accessAndDocAware.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
+    );
   }
 }

package/src/{__spec__/core → core/markdown/__test__}/expect-extensions.ts

@@ -1,5 +1,5 @@
 import * as E from 'fp-ts/Either';
-import { DocumentationBundle } from '../../core/generate-docs';
+import { DocumentationBundle } from '../../shared/types';
 
 export function extendExpect() {
   expect.extend({
@@ -11,14 +11,14 @@ export function extendExpect() {
     },
     firstDocContains(doc: DocumentationBundle, content: string) {
       return {
-        pass: doc.docs[0].docContents.includes(content),
-        message: () => `Expected documentation to contain ${content}. Got ${doc.docs[0].docContents}`,
+        pass: doc.docs[0].content.includes(content),
+        message: () => `Expected documentation to contain ${content}. Got ${doc.docs[0].content}`,
       };
     },
     firstDocContainsNot(doc: DocumentationBundle, content: string) {
       return {
-        pass: !doc.docs[0].docContents.includes(content),
-        message: () => `Expected documentation to not contain ${content}. Got ${doc.docs[0].docContents}`,
+        pass: !doc.docs[0].content.includes(content),
+        message: () => `Expected documentation to not contain ${content}. Got ${doc.docs[0].content}`,
       };
     },
   });