@cparra/apexdocs 2.25.0-alpha.8 → 2.25.0

package/src/model/manifest.ts

@@ -0,0 +1,74 @@
+import {
+  ClassMirror,
+  EnumMirror,
+  InterfaceMirror,
+  Type,
+  Annotation,
+  DocComment,
+  DocCommentAnnotation,
+} from '@cparra/apex-reflection';
+
+type AccessAndDocAware = { access_modifier: string; annotations: Annotation[]; docComment?: DocComment };
+
+/**
+ * Represents the full library of Apex top-level types (classes, enums, and interface) for a Salesforce project.
+ */
+export default class Manifest {
+  /**
+   * Constructs a new Manifest object.
+   * @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) {}
+
+  filteredByAccessModifierAndAnnotations(modifiers: string[]): Type[] {
+    const filteredTypes = this.filterAccessibleModifier(this.types, modifiers);
+    const typesToReturn: Type[] = [];
+    for (const filteredType of filteredTypes) {
+      const currentType = filteredType as Type;
+      if (currentType.type_name !== 'class') {
+        typesToReturn.push(currentType);
+        continue;
+      }
+
+      const currentClass = currentType as ClassMirror;
+      let 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),
+      };
+
+      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[],
+        };
+      }
+
+      typesToReturn.push(filteredClass as ClassMirror);
+    }
+
+    return typesToReturn;
+  }
+
+  filterAccessibleModifier(accessAndDocAwares: AccessAndDocAware[], modifiers: string[]) {
+    return accessAndDocAwares.filter((currentType) => {
+      const hasIgnoreDocAnnotation = currentType.docComment?.annotations.some(
+        (annotation: DocCommentAnnotation) => annotation.name === 'ignore',
+      );
+      if (hasIgnoreDocAnnotation) {
+        return false;
+      }
+      return (
+        modifiers.includes(currentType.access_modifier) ||
+        currentType.annotations.some((annotation: Annotation) => modifiers.includes(annotation.type.toLowerCase()))
+      );
+    });
+  }
+}

package/src/model/markdown-file.ts

@@ -0,0 +1,121 @@
+import { OutputFile } from './outputFile';
+import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
+
+export class MarkdownFile extends OutputFile {
+  fileExtension(): string {
+    return '.md';
+  }
+
+  addTitle(text: string, level = 1) {
+    let title = '';
+    for (let i = 0; i < level; i++) {
+      title += '#';
+    }
+
+    title += ' ';
+    title += text;
+    this._contents += title;
+    this.addBlankLine();
+  }
+
+  public addText(text: string, encodeHtml = true) {
+    super.addText(this._replaceInlineReferences(text), encodeHtml);
+  }
+
+  public addLink(text: string, encodeHtml = true) {
+    this.addText(`\{@link ${text}\}`, encodeHtml);
+  }
+
+  startCodeBlock(language = 'apex') {
+    this.addText(`\`\`\`${language}`);
+  }
+
+  endCodeBlock() {
+    this.addText('```');
+    this.addBlankLine();
+  }
+
+  addHorizontalRule() {
+    this._contents += '---';
+    this.addBlankLine();
+  }
+
+  initializeTable(...headers: string[]) {
+    this.addBlankLine();
+    this._contents += '|';
+    headers.forEach((header) => {
+      this._contents += header + '|';
+    });
+    this.addBlankLine();
+    this._contents += '|';
+    headers.forEach((_) => {
+      this._contents += '---' + '|';
+    });
+    this.addBlankLine();
+  }
+
+  addTableRow(...columns: string[]) {
+    this._contents += '|';
+    columns.forEach((column) => {
+      this._contents += this._replaceInlineReferences(column) + '|';
+    });
+    this.addBlankLine();
+  }
+
+  addListItem(text: string) {
+    this._contents += `* ${text}`;
+  }
+
+  protected static replaceInlineLinks(text: string) {
+    // Parsing text to extract possible linking classes.
+    const possibleLinks = text.match(/<<.*?>>/g);
+    possibleLinks?.forEach((currentMatch) => {
+      const classNameForMatch = currentMatch.replace('<<', '').replace('>>', '');
+      text = text.replace(currentMatch, ClassFileGeneratorHelper.getFileLinkByTypeName(classNameForMatch));
+    });
+
+    // Parsing links using {@link ClassName} format
+    const linkFormatRegEx = '{@link (.*?)}';
+    const expression = new RegExp(linkFormatRegEx, 'gi');
+    let match;
+    const matches = [];
+
+    do {
+      match = expression.exec(text);
+      if (match) {
+        matches.push(match);
+      }
+    } while (match);
+
+    for (const currentMatch of matches) {
+      text = text.replace(currentMatch[0], ClassFileGeneratorHelper.getFileLinkByTypeName(currentMatch[1]));
+    }
+    return text;
+  }
+
+  protected static replaceInlineEmails(text: string) {
+    // Parsing links using {@link ClassName} format
+    const linkFormatRegEx = '{@email (.*?)}';
+    const expression = new RegExp(linkFormatRegEx, 'gi');
+    let match;
+    const matches = [];
+
+    do {
+      match = expression.exec(text);
+      if (match) {
+        matches.push(match);
+      }
+    } while (match);
+
+    for (const currentMatch of matches) {
+      text = text.replace(currentMatch[0], `[${currentMatch[1]}](mailto:${currentMatch[1]})`);
+    }
+    return text;
+  }
+
+  private _replaceInlineReferences(text: string): string {
+    text = MarkdownFile.replaceInlineLinks(text);
+    text = MarkdownFile.replaceInlineEmails(text);
+    return text;
+  }
+}

package/src/model/markdown-generation-util/doc-comment-annotation-util.ts

@@ -0,0 +1,50 @@
+import { DocComment, DocCommentAnnotation } from '@cparra/apex-reflection';
+import ClassFileGeneratorHelper from '../../transpiler/markdown/class-file-generatorHelper';
+import { MarkdownFile } from '../markdown-file';
+
+interface DocCommentAware {
+  docComment?: DocComment;
+}
+
+export function addMermaid(markdownFile: MarkdownFile, docCommentAware: DocCommentAware) {
+  const mermaid = docCommentAware.docComment?.annotations.find((annotation) => annotation.name === 'mermaid');
+  if (!mermaid) {
+    return;
+  }
+
+  markdownFile.addBlankLine();
+  markdownFile.startCodeBlock('mermaid');
+  mermaid.bodyLines.forEach((line) => {
+    markdownFile.addText(line, false);
+  });
+  markdownFile.endCodeBlock();
+  markdownFile.addBlankLine();
+}
+
+export function addCustomDocCommentAnnotations(markdownFile: MarkdownFile, docCommentAware: DocCommentAware) {
+  docCommentAware.docComment?.annotations
+    .filter((currentAnnotation: DocCommentAnnotation) => currentAnnotation.name !== 'description')
+    .filter((currentAnnotation: DocCommentAnnotation) => currentAnnotation.name !== 'mermaid')
+    .forEach((currentAnnotation: DocCommentAnnotation) => {
+      markdownFile.addBlankLine();
+      markdownFile.addText(buildDocAnnotationText(currentAnnotation));
+      markdownFile.addBlankLine();
+    });
+
+  function splitAndCapitalize(text: string) {
+    const words = text.split(/[-_]+/);
+    const capitalizedWords = [];
+    for (const word of words) {
+      capitalizedWords.push(word.charAt(0).toUpperCase() + word.slice(1));
+    }
+    return capitalizedWords.join(' ');
+  }
+
+  function buildDocAnnotationText(annotation: DocCommentAnnotation) {
+    let annotationBodyText = annotation.body;
+    if (annotation.name.toLowerCase() === 'see') {
+      annotationBodyText = ClassFileGeneratorHelper.getFileLinkByTypeName(annotation.body);
+    }
+    return `**${splitAndCapitalize(annotation.name)}** ${annotationBodyText}`;
+  }
+}

package/src/model/markdown-generation-util/field-declaration-util.ts

@@ -0,0 +1,71 @@
+import { MarkdownFile } from '../markdown-file';
+import { FieldMirrorWithInheritance, FieldOrProperty, PropertyMirrorWithInheritance } from '../inheritance';
+
+export function declareField(
+  markdownFile: MarkdownFile,
+  fields: FieldMirrorWithInheritance[] | PropertyMirrorWithInheritance[],
+  startingHeadingLevel: number,
+  grouped = false,
+) {
+  markdownFile.addBlankLine();
+  fields.forEach((propertyModel) => {
+    addFieldSection(markdownFile, propertyModel, startingHeadingLevel, grouped);
+  });
+
+  markdownFile.addHorizontalRule();
+}
+
+function addFieldSection(
+  markdownFile: MarkdownFile,
+  mirrorModel: FieldOrProperty,
+  startingHeadingLevel: number,
+  grouped: boolean,
+) {
+  if (!grouped) {
+    markdownFile.addTitle(
+      `\`${mirrorModel.access_modifier} ${mirrorModel.name}\` → \`${mirrorModel.typeReference.rawDeclaration}\``,
+      startingHeadingLevel + 2,
+    );
+    markdownFile.addBlankLine();
+    if (mirrorModel.inherited) {
+      markdownFile.addText('*Inherited*');
+    }
+
+    mirrorModel.annotations.forEach((annotation) => {
+      markdownFile.addText(`\`${annotation.type.toUpperCase()}\` `);
+    });
+
+    if (mirrorModel.docComment?.description) {
+      markdownFile.addBlankLine();
+      markdownFile.addText(mirrorModel.docComment.description);
+    }
+    markdownFile.addBlankLine();
+  } else {
+    let annotations = '';
+    const hasAnnotations = !!mirrorModel.annotations.length;
+    if (hasAnnotations) {
+      annotations += ' [';
+    }
+    mirrorModel.annotations.forEach((annotation) => {
+      annotations += `\`${annotation.type.toUpperCase()}\` `;
+    });
+    if (hasAnnotations) {
+      annotations += ']';
+    }
+
+    // If grouped we want to display these as a list
+    let description = '';
+    if (mirrorModel.docComment?.description) {
+      description = ` - ${mirrorModel.docComment?.description}`;
+    }
+
+    let listItemText = `\`${mirrorModel.access_modifier} ${mirrorModel.name}\` → \`${mirrorModel.typeReference.rawDeclaration}\``;
+    if (mirrorModel.inherited) {
+      listItemText += '(*Inherited*)';
+    }
+    listItemText += `${annotations} ${description}`;
+
+    markdownFile.addListItem(listItemText);
+    markdownFile.addBlankLine();
+  }
+}

package/src/model/markdown-generation-util/index.ts

@@ -0,0 +1,3 @@
+export * from './type-declaration-util';
+export * from './method-declaration-util';
+export * from './field-declaration-util';

package/src/model/markdown-generation-util/method-declaration-util.ts

@@ -0,0 +1,166 @@
+import { ConstructorMirror, DocComment } from '@cparra/apex-reflection';
+import { MarkdownFile } from '../markdown-file';
+import { ParameterMirror } from '@cparra/apex-reflection';
+import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
+import { MethodMirrorWithInheritance } from '../inheritance';
+
+export function declareMethod(
+  markdownFile: MarkdownFile,
+  methods: ConstructorMirror[] | MethodMirrorWithInheritance[],
+  startingHeadingLevel: number,
+  className = '',
+): void {
+  methods.forEach((currentMethod) => {
+    const signatureName = isMethod(currentMethod)
+      ? `${(currentMethod as MethodMirrorWithInheritance).typeReference.rawDeclaration} ${
+          (currentMethod as MethodMirrorWithInheritance).name
+        }`
+      : className;
+
+    markdownFile.addTitle(
+      `\`${buildSignature(currentMethod.access_modifier, signatureName, currentMethod)}\``,
+      startingHeadingLevel + 2,
+    );
+
+    // Inheritance tag
+    if (isMethod(currentMethod)) {
+      const asMethodMirror = currentMethod as MethodMirrorWithInheritance;
+      if (asMethodMirror.inherited) {
+        markdownFile.addBlankLine();
+        markdownFile.addText('*Inherited*');
+        markdownFile.addBlankLine();
+      }
+    }
+
+    currentMethod.annotations.forEach((annotation) => {
+      markdownFile.addBlankLine();
+      markdownFile.addText(`\`${annotation.type.toUpperCase()}\``);
+    });
+
+    if (currentMethod.docComment?.description) {
+      markdownFile.addBlankLine();
+      markdownFile.addText(currentMethod.docComment.description);
+      markdownFile.addBlankLine();
+    }
+
+    if (currentMethod.parameters.length) {
+      addParameters(markdownFile, currentMethod, startingHeadingLevel);
+    }
+
+    if (isMethod(currentMethod)) {
+      addReturns(markdownFile, currentMethod as MethodMirrorWithInheritance, startingHeadingLevel);
+    }
+
+    addThrowsBlock(markdownFile, currentMethod, startingHeadingLevel);
+
+    addCustomDocCommentAnnotations(markdownFile, currentMethod);
+
+    addMermaid(markdownFile, currentMethod);
+
+    if (currentMethod.docComment?.exampleAnnotation) {
+      addExample(markdownFile, currentMethod, startingHeadingLevel);
+    }
+  });
+
+  markdownFile.addHorizontalRule();
+}
+
+type ParameterAware = {
+  parameters: ParameterMirror[];
+};
+
+type DocCommentAware = {
+  docComment?: DocComment;
+};
+
+function buildSignature(accessModifier: string, name: string, parameterAware: ParameterAware): string {
+  let signature = `${name}(`;
+  if (isMethod(parameterAware) && (parameterAware as MethodMirrorWithInheritance).memberModifiers.length) {
+    signature =
+      accessModifier +
+      ' ' +
+      (parameterAware as MethodMirrorWithInheritance).memberModifiers.join(' ') +
+      ' ' +
+      signature;
+  } else {
+    signature = accessModifier + ' ' + signature;
+  }
+  const signatureParameters = parameterAware.parameters.map(
+    (param) => `${param.typeReference.rawDeclaration} ${param.name}`,
+  );
+  signature += signatureParameters.join(', ');
+  return `${signature})`;
+}
+
+function addParameters(
+  markdownFile: MarkdownFile,
+  methodModel: MethodMirrorWithInheritance | ConstructorMirror,
+  startingHeadingLevel: number,
+) {
+  if (!methodModel.docComment?.paramAnnotations.length) {
+    // If there are no parameters defined in the docs then we don't want to display this section
+    return;
+  }
+
+  markdownFile.addTitle('Parameters', startingHeadingLevel + 3);
+  markdownFile.initializeTable('Param', 'Description');
+
+  methodModel.docComment?.paramAnnotations.forEach((paramAnnotation) => {
+    const paramName = paramAnnotation.paramName;
+    const paramDescription = paramAnnotation.bodyLines.join(' ');
+    markdownFile.addTableRow(`\`${paramName}\``, paramDescription);
+  });
+
+  markdownFile.addBlankLine();
+}
+
+function addReturns(
+  markdownFile: MarkdownFile,
+  methodModel: MethodMirrorWithInheritance,
+  startingHeadingLevel: number,
+) {
+  if (!methodModel.docComment?.returnAnnotation) {
+    return;
+  }
+
+  markdownFile.addTitle('Returns', startingHeadingLevel + 3);
+  markdownFile.initializeTable('Type', 'Description');
+  markdownFile.addTableRow(
+    `\`${methodModel.typeReference.rawDeclaration}\``,
+    methodModel.docComment?.returnAnnotation.bodyLines.join(' '),
+  );
+  markdownFile.addBlankLine();
+}
+
+function addThrowsBlock(markdownFile: MarkdownFile, docCommentAware: DocCommentAware, startingHeadingLevel: number) {
+  if (!docCommentAware.docComment?.throwsAnnotations.length) {
+    return;
+  }
+  markdownFile.addTitle('Throws', startingHeadingLevel + 3);
+  markdownFile.initializeTable('Exception', 'Description');
+
+  docCommentAware.docComment?.throwsAnnotations.forEach((annotation) => {
+    const exceptionName = annotation.exceptionName;
+    const exceptionDescription = annotation.bodyLines.join(' ');
+
+    markdownFile.addTableRow(`\`${exceptionName}\``, exceptionDescription);
+  });
+
+  markdownFile.addBlankLine();
+}
+
+function addExample(markdownFile: MarkdownFile, docCommentAware: DocCommentAware, startingHeadingLevel: number) {
+  markdownFile.addTitle('Example', startingHeadingLevel + 3);
+  markdownFile.startCodeBlock();
+  docCommentAware.docComment?.exampleAnnotation.bodyLines.forEach((line) => {
+    markdownFile.addText(line, false);
+  });
+  markdownFile.endCodeBlock();
+  markdownFile.addBlankLine();
+}
+
+function isMethod(
+  method: MethodMirrorWithInheritance | ConstructorMirror | ParameterAware,
+): method is MethodMirrorWithInheritance {
+  return (method as MethodMirrorWithInheritance).typeReference !== undefined;
+}

package/src/model/markdown-generation-util/type-declaration-util.ts

@@ -0,0 +1,91 @@
+import { MarkdownFile } from '../markdown-file';
+import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
+import { Annotation, ClassMirror, InterfaceMirror, Type } from '@cparra/apex-reflection';
+import { TypesRepository } from '../types-repository';
+
+export function declareType(markdownFile: MarkdownFile, typeMirror: Type): void {
+  typeMirror.annotations.forEach((currentAnnotation: Annotation) => {
+    markdownFile.addBlankLine();
+    markdownFile.addText(`\`${currentAnnotation.type.toUpperCase()}\``);
+  });
+
+  if (typeMirror.docComment?.descriptionLines) {
+    markdownFile.addBlankLine();
+    for (const currentLine of typeMirror.docComment.descriptionLines) {
+      markdownFile.addText(currentLine);
+    }
+    markdownFile.addBlankLine();
+  }
+
+  if (typeMirror.type_name === 'class') {
+    addInheritanceSectionForClass(typeMirror, markdownFile);
+  }
+
+  if (typeMirror.type_name === 'interface') {
+    addInheritanceSectionForInterface(typeMirror, markdownFile);
+  }
+
+  addCustomDocCommentAnnotations(markdownFile, typeMirror);
+
+  addMermaid(markdownFile, typeMirror);
+}
+
+function addInheritanceSectionForClass(typeMirror: Type, markdownFile: MarkdownFile) {
+  const typeAsClass = typeMirror as ClassMirror;
+  if (typeAsClass.extended_class) {
+    markdownFile.addBlankLine();
+    markdownFile.addText('**Inheritance**');
+    markdownFile.addBlankLine();
+    addParent(markdownFile, typeAsClass);
+    markdownFile.addText(typeMirror.name);
+    markdownFile.addBlankLine();
+  }
+
+  if (typeAsClass.implemented_interfaces.length) {
+    markdownFile.addBlankLine();
+    markdownFile.addText('**Implemented types**');
+    markdownFile.addBlankLine();
+    for (let i = 0; i < typeAsClass.implemented_interfaces.length; i++) {
+      const currentName = typeAsClass.implemented_interfaces[i];
+      markdownFile.addLink(currentName);
+      if (i < typeAsClass.implemented_interfaces.length - 1) {
+        markdownFile.addText(', ');
+      }
+    }
+    markdownFile.addBlankLine();
+  }
+}
+
+function addInheritanceSectionForInterface(typeMirror: Type, markdownFile: MarkdownFile) {
+  const typeAsInterface = typeMirror as InterfaceMirror;
+  if (typeAsInterface.extended_interfaces.length) {
+    markdownFile.addBlankLine();
+    markdownFile.addText('**Extended types**');
+    markdownFile.addBlankLine();
+    for (let i = 0; i < typeAsInterface.extended_interfaces.length; i++) {
+      const currentName = typeAsInterface.extended_interfaces[i];
+      markdownFile.addLink(currentName);
+      if (i < typeAsInterface.extended_interfaces.length - 1) {
+        markdownFile.addText(', ');
+      }
+    }
+  }
+}
+
+function addParent(markdownFile: MarkdownFile, classMirror: ClassMirror) {
+  if (!classMirror.extended_class) {
+    return;
+  }
+
+  const parentType = TypesRepository.getInstance().getFromScopedByName(classMirror.extended_class);
+  if (!parentType) {
+    return;
+  }
+
+  if (parentType.type_name === 'class') {
+    addParent(markdownFile, parentType as ClassMirror);
+  }
+
+  markdownFile.addLink(parentType.name);
+  markdownFile.addText(' > ');
+}

package/src/model/markdown-home-file.ts

@@ -0,0 +1,58 @@
+import { Type } from '@cparra/apex-reflection';
+import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
+import { MarkdownFile } from './markdown-file';
+import { truncate } from '../util/string-utils';
+import { Settings } from '../settings';
+
+export class MarkdownHomeFile extends MarkdownFile {
+  constructor(public fileName: string, public types: Type[], headerContent?: string) {
+    super(fileName, '');
+    if (headerContent) {
+      this.addText(headerContent);
+    }
+    this.addTitle(Settings.getInstance().getTitle());
+    this.addTypeEntries(types);
+  }
+
+  private addTypeEntries(types: Type[]) {
+    const groupedClasses: Map<string, Type[]> = this.group(types);
+    groupedClasses.forEach((value: Type[], key: string) => {
+      this.addTitle(key, 2);
+      value.forEach((typeMirror) => {
+        this.addTypeEntry(typeMirror);
+      });
+    });
+  }
+
+  private addTypeEntry(typeMirror: Type) {
+    this.addBlankLine();
+    this.addTitle(ClassFileGeneratorHelper.getFileLink(typeMirror), 3);
+    this.addBlankLine();
+
+    if (typeMirror.docComment?.descriptionLines) {
+      const description = typeMirror.docComment.descriptionLines.reduce(
+        (previous, current) => previous + current + '\n',
+        '',
+      );
+      this.addText(truncate(description, 300));
+      this.addBlankLine();
+    }
+  }
+
+  private group(classes: Type[]): Map<string, Type[]> {
+    return classes.reduce((groups, currentClass) => {
+      const key = this.getClassGroup(currentClass);
+      const group: Type[] = groups.get(key) || [];
+      group.push(currentClass);
+      groups.set(key, group);
+      return groups;
+    }, new Map());
+  }
+
+  private getClassGroup(classModel: Type): string {
+    return (
+      classModel.docComment?.annotations.find((annotation) => annotation.name === 'group')?.body ??
+      Settings.getInstance().getDefaultGroupName()
+    );
+  }
+}