@cparra/apexdocs 3.0.0-rc.0 → 3.0.0

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

@@ -1,22 +1,6 @@
-import { ParsedFile } from '../../../shared/types';
-import { ClassMirror, EnumMirror, InterfaceMirror, reflect } from '@cparra/apex-reflection';
+import { ClassMirror, EnumMirror, InterfaceMirror } 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!,
-  };
-}
+import { parsedFileFromRawString } from './helpers';
 
 describe('When filtering scope', () => {
   it('filters out files with the @ignore annotation', () => {

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

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

@@ -0,0 +1,168 @@
+import * as O from 'fp-ts/Option';
+import { match } from 'fp-ts/boolean';
+import { ParsedFile } from '../../shared/types';
+import { ClassMirror, DocComment, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import { pipe } from 'fp-ts/function';
+import { apply } from '#utils/fp';
+
+type AppliedRemoveTagFn = (tagName: string, removeFn: RemoveTagFn) => DocComment;
+type RemoveTagFn = (docComment: DocComment) => DocComment;
+type Documentable = { docComment?: DocComment };
+
+export const removeExcludedTags = (excludedTags: string[], parsedFiles: ParsedFile[]): ParsedFile[] => {
+  return parsedFiles.map((parsedFile) => {
+    return {
+      ...parsedFile,
+      type: removeExcludedTagsFromType(excludedTags, parsedFile.type),
+    };
+  });
+};
+
+const removeExcludedTagsFromType = <T extends Type>(excludedTags: string[], type: T): T => {
+  return {
+    ...handleType(excludedTags, type),
+    docComment: removeExcludedTagsFromDocComment(excludedTags, type.docComment),
+  } as T;
+};
+
+const handleType = (excludedTags: string[], type: Type): Type => {
+  switch (type.type_name) {
+    case 'class':
+      return handleClass(excludedTags, type as ClassMirror);
+    case 'interface':
+      return handleInterface(excludedTags, type as InterfaceMirror);
+    case 'enum':
+      return type;
+  }
+};
+
+const handleClass = (excludedTags: string[], classMirror: ClassMirror): ClassMirror => {
+  return {
+    ...classMirror,
+    methods: classMirror.methods.map((method) => removeExcludedTagsFromDocumentable(excludedTags, method)),
+    properties: classMirror.properties.map((property) => removeExcludedTagsFromDocumentable(excludedTags, property)),
+    fields: classMirror.fields.map((field) => removeExcludedTagsFromDocumentable(excludedTags, field)),
+    constructors: classMirror.constructors.map((constructor) =>
+      removeExcludedTagsFromDocumentable(excludedTags, constructor),
+    ),
+    enums: classMirror.enums.map((enumType) => removeExcludedTagsFromType(excludedTags, enumType)),
+    interfaces: classMirror.interfaces.map((interfaceType) => removeExcludedTagsFromType(excludedTags, interfaceType)),
+    classes: classMirror.classes.map((innerClass) => removeExcludedTagsFromType(excludedTags, innerClass)),
+  };
+};
+
+const handleInterface = (excludedTags: string[], interfaceMirror: InterfaceMirror): InterfaceMirror => {
+  return {
+    ...interfaceMirror,
+    methods: interfaceMirror.methods.map((method) => removeExcludedTagsFromDocumentable(excludedTags, method)),
+  };
+};
+
+const removeExcludedTagsFromDocumentable = <T extends Documentable>(excludedTags: string[], documentable: T): T => {
+  return {
+    ...documentable,
+    docComment: removeExcludedTagsFromDocComment(excludedTags, documentable.docComment),
+  };
+};
+
+const removeExcludedTagsFromDocComment = (
+  excludedTags: string[],
+  docComment: DocComment | undefined,
+): DocComment | undefined => {
+  const removerFn = apply(remove, excludedTags);
+
+  return pipe(
+    O.fromNullable(docComment),
+    O.map((docComment) => removeExcludedTagsFromAnnotations(excludedTags, docComment)),
+    O.map((docComment) => removeExampleTag(apply(removerFn, docComment))),
+    O.map((docComment) => removeParamTags(apply(removerFn, docComment))),
+    O.map((docComment) => removeReturnTag(apply(removerFn, docComment))),
+    O.map((docComment) => removeThrowsTag(apply(removerFn, docComment))),
+    O.map((docComment) => removeExceptionTag(apply(removerFn, docComment))),
+    O.map((docComment) => removeDescription(apply(removerFn, docComment))),
+    O.fold(
+      () => undefined,
+      (updatedDocComment) => updatedDocComment,
+    ),
+  );
+};
+
+const removeExcludedTagsFromAnnotations = (excludedTags: string[], docComment: DocComment): DocComment => {
+  return pipe(
+    O.some(docComment.annotations),
+    O.map((annotations) => annotations.filter((annotation) => !includesIgnoreCase(excludedTags, annotation.name))),
+    O.fold(
+      () => docComment,
+      (filteredAnnotations) => ({
+        ...docComment,
+        annotations: filteredAnnotations,
+      }),
+    ),
+  );
+};
+
+const removeExampleTag = (remover: AppliedRemoveTagFn): DocComment => {
+  return remover('example', (docComment) => {
+    return {
+      ...docComment,
+      exampleAnnotation: null,
+    };
+  });
+};
+
+const removeParamTags = (remover: AppliedRemoveTagFn): DocComment => {
+  return remover('param', (docComment) => {
+    return {
+      ...docComment,
+      paramAnnotations: [],
+    };
+  });
+};
+
+const removeReturnTag = (remover: AppliedRemoveTagFn): DocComment => {
+  return remover('return', (docComment) => {
+    return {
+      ...docComment,
+      returnAnnotation: null,
+    };
+  });
+};
+
+const removeThrowsTag = (remover: AppliedRemoveTagFn): DocComment => {
+  return remover('throws', (docComment) => {
+    return {
+      ...docComment,
+      throwsAnnotations: [],
+    };
+  });
+};
+
+const removeExceptionTag = (remover: AppliedRemoveTagFn): DocComment => {
+  return remover('exception', (docComment) => {
+    return {
+      ...docComment,
+      throwsAnnotations: [],
+    };
+  });
+};
+
+const removeDescription = (remover: AppliedRemoveTagFn): DocComment => {
+  return remover('description', (docComment) => {
+    return {
+      ...docComment,
+      description: '',
+      descriptionLines: [],
+    };
+  });
+};
+
+const remove = (excludedTags: string[], docComment: DocComment, tagName: string, removeFn: RemoveTagFn): DocComment => {
+  return match(
+    () => docComment,
+    () => removeFn(docComment!),
+  )(includesIgnoreCase(excludedTags, tagName) && !!docComment);
+};
+
+const includesIgnoreCase = (excluded: string[], value: string): boolean => {
+  return excluded.some((element) => element.toLowerCase() === value.toLowerCase());
+};

package/src/core/markdown/reflection/{sort-members.ts → sort-types-and-members.ts}

@@ -3,11 +3,13 @@ import { ParsedFile } from '../../shared/types';
 
 type Named = { name: string };
 
-export function sortMembers(shouldSortMembers: boolean, parsedFiles: ParsedFile[]): ParsedFile[] {
-  return parsedFiles.map((parsedFile) => ({
-    ...parsedFile,
-    type: sortTypeMember(parsedFile.type, shouldSortMembers),
-  }));
+export function sortTypesAndMembers(shouldSort: boolean, parsedFiles: ParsedFile[]): ParsedFile[] {
+  return parsedFiles
+    .map((parsedFile) => ({
+      ...parsedFile,
+      type: sortTypeMember(parsedFile.type, shouldSort),
+    }))
+    .sort((a, b) => sortByNames(shouldSort, a.type, b.type));
 }
 
 function sortByNames<T extends Named>(shouldSort: boolean, a: T, b: T): number {

package/src/core/markdown/templates/reference-guide.ts

@@ -1,7 +1,7 @@
 export const referenceGuideTemplate = `
-# Apex Reference Guide
+# {{referenceGuideTitle}}
 
-{{#each this}}
+{{#each references}}
 ## {{@key}}
 
 {{#each this}}

package/src/core/openapi/__tests__/open-api-docs-processor.spec.ts

@@ -4,6 +4,9 @@ import { SettingsBuilder } from '../../../test-helpers/SettingsBuilder';
 import { DocCommentBuilder } from '../../../test-helpers/DocCommentBuilder';
 import { AnnotationBuilder } from '../../../test-helpers/AnnotationBuilder';
 import { ClassMirrorBuilder } from '../../../test-helpers/ClassMirrorBuilder';
+import { NoLogger } from '../../../util/logger';
+
+const noLogger = new NoLogger();
 
 beforeEach(() => {
   OpenApiSettings.build(new SettingsBuilder().build());
@@ -18,7 +21,7 @@ it('should add a path based on the @UrlResource annotation on the class', functi
     .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
     .build();
 
-  const processor = new OpenApiDocsProcessor();
+  const processor = new OpenApiDocsProcessor(noLogger);
   processor.onProcess(classMirror);
 
   expect(processor.openApiModel.paths).toHaveProperty('Account/');
@@ -33,7 +36,7 @@ it('should respect slashes', function () {
     .addAnnotation(new AnnotationBuilder().addElementValue(annotationElementValue).build())
     .build();
 
-  const processor = new OpenApiDocsProcessor();
+  const processor = new OpenApiDocsProcessor(noLogger);
   processor.onProcess(classMirror);
 
   expect(processor.openApiModel.paths).toHaveProperty('v1/Account/');
@@ -49,7 +52,7 @@ it('should contain a path with a description when the class has an ApexDoc comme
     .withDocComment(new DocCommentBuilder().withDescription('My Description').build())
     .build();
 
-  const processor = new OpenApiDocsProcessor();
+  const processor = new OpenApiDocsProcessor(noLogger);
   processor.onProcess(classMirror);
 
   expect(processor.openApiModel.paths['Account/'].description).toBe('My Description');

package/src/core/openapi/open-api-docs-processor.ts

@@ -11,7 +11,7 @@ export class OpenApiDocsProcessor {
   protected readonly _fileContainer: FileContainer;
   openApiModel: OpenApi;
 
-  constructor() {
+  constructor(private logger: Logger) {
     this._fileContainer = new FileContainer();
     const title = OpenApiSettings.getInstance().getOpenApiTitle();
     if (!title) {
@@ -29,7 +29,7 @@ export class OpenApiDocsProcessor {
   }
 
   onProcess(type: Type): void {
-    Logger.logSingle(`Processing ${type.name}`, 'green');
+    this.logger.logSingle(`Processing ${type.name}`, 'green');
 
     const endpointPath = this.getEndpointPath(type);
     if (!endpointPath) {
@@ -80,7 +80,7 @@ export class OpenApiDocsProcessor {
       (element) => element.key.toLowerCase() === 'urlmapping',
     );
     if (!urlMapping) {
-      Logger.error(`Type does not contain urlMapping annotation ${type.name}`);
+      this.logger.error(`Type does not contain urlMapping annotation ${type.name}`);
       return null;
     }
 

package/src/core/openapi/parser.ts

@@ -9,12 +9,15 @@ export interface TypeParser {
 type NameAware = { name: string };
 
 export class RawBodyParser implements TypeParser {
-  constructor(public typeBundles: UnparsedSourceFile[]) {}
+  constructor(
+    private logger: Logger,
+    public typeBundles: UnparsedSourceFile[],
+  ) {}
 
   parse(reflect: (apexBundle: UnparsedSourceFile) => ReflectionResult): Type[] {
     const types = this.typeBundles
       .map((currentBundle) => {
-        Logger.log(`Parsing file: ${currentBundle.filePath}`);
+        this.logger.log(`Parsing file: ${currentBundle.filePath}`);
         return reflect(currentBundle);
       })
       .filter((reflectionResult) => {

package/src/core/shared/types.d.ts

@@ -16,11 +16,13 @@ export type UserDefinedMarkdownConfig = {
   targetGenerator: 'markdown';
   targetDir: string;
   scope: string[];
-  defaultGroupName: string;
   namespace?: string;
-  sortMembersAlphabetically: boolean;
+  defaultGroupName: string;
+  sortAlphabetically: boolean;
   includeMetadata: boolean;
   linkingStrategy: LinkingStrategy;
+  excludeTags: string[];
+  referenceGuideTitle: string;
 } & Partial<ConfigurableHooks>;
 
 export type UserDefinedOpenApiConfig = {

package/src/defaults.ts

@@ -1,9 +1,21 @@
-export const defaults = {
-  targetGenerator: 'markdown' as const,
+const commonDefaults = {
   targetDir: './docs/',
+};
+
+export const markdownDefaults = {
+  ...commonDefaults,
   scope: ['global'],
   defaultGroupName: 'Miscellaneous',
   includeMetadata: false,
-  sortMembersAlphabetically: false,
+  sortAlphabetically: false,
   linkingStrategy: 'relative' as const,
+  referenceGuideTitle: 'Apex Reference Guide',
+  excludeTags: [],
+};
+
+export const openApiDefaults = {
+  ...commonDefaults,
+  fileName: 'openapi',
+  title: 'Apex REST API',
+  apiVersion: '1.0.0',
 };