@cparra/apexdocs 2.23.0 → 2.25.0-alpha.0

package/src/adapters/methods-and-constructors.ts

@@ -0,0 +1,78 @@
+import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
+import { ConstructorSource, MethodSource } from '../templating/types';
+import { MethodMirrorWithInheritance } from '../model/inheritance';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { linkFromTypeNameGenerator } from './references';
+import { Documentable } from './types';
+
+export function adaptMethod(method: MethodMirror): MethodSource {
+  function buildTitle(method: MethodMirrorWithInheritance): string {
+    const { name, parameters } = method;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(method: MethodMirrorWithInheritance): string {
+    const { access_modifier, typeReference, name, memberModifiers } = method;
+    const parameters = method.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    const members = memberModifiers.length > 0 ? `${memberModifiers.join(' ')} ` : '';
+    return `${access_modifier} ${members}${typeReference.rawDeclaration} ${name}(${parameters})`;
+  }
+
+  return {
+    ...adaptDocumentable(method),
+    title: buildTitle(method as MethodMirrorWithInheritance),
+    signature: buildSignature(method as MethodMirrorWithInheritance),
+    returnType: {
+      ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines),
+      type: linkFromTypeNameGenerator(method.typeReference.rawDeclaration),
+    },
+    throws: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+    parameters: method.parameters.map((param) => mapParameters(method, param)),
+    inherited: (method as MethodMirrorWithInheritance).inherited,
+  };
+}
+
+export function adaptConstructor(typeName: string, constructor: ConstructorMirror): ConstructorSource {
+  function buildTitle(name: string, constructor: ConstructorMirror): string {
+    const { parameters } = constructor;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(name: string, constructor: ConstructorMirror): string {
+    const { access_modifier } = constructor;
+    const parameters = constructor.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    return `${access_modifier} ${name}(${parameters})`;
+  }
+
+  return {
+    ...adaptDocumentable(constructor),
+    title: buildTitle(typeName, constructor),
+    signature: buildSignature(typeName, constructor),
+    parameters: constructor.parameters.map((param) => mapParameters(constructor, param)),
+    throws: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+  };
+}
+
+function mapParameters(documentable: Documentable, param: ParameterMirror) {
+  const paramAnnotation = documentable.docComment?.paramAnnotations.find(
+    (pa) => pa.paramName.toLowerCase() === param.name.toLowerCase(),
+  );
+  return {
+    ...adaptDescribable(paramAnnotation?.bodyLines),
+    name: param.name,
+    type: linkFromTypeNameGenerator(param.typeReference.rawDeclaration),
+  };
+}
+
+function mapThrows(thrown: ThrowsAnnotation) {
+  return {
+    ...adaptDescribable(thrown.bodyLines),
+    type: linkFromTypeNameGenerator(thrown.exceptionName),
+  };
+}

package/src/adapters/references.ts

@@ -0,0 +1,113 @@
+import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
+import { Link, RenderableContent, StringOrLink } from '../templating/types';
+
+export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+
+export const linkFromTypeNameGenerator: GetRenderableContentByTypeName =
+  ClassFileGeneratorHelper.getRenderableLinkByTypeName;
+
+function defaultGetEmailByReference(email: string): Link {
+  return {
+    title: email,
+    url: `mailto:${email}`,
+  };
+}
+
+export function replaceInlineReferences(
+  text: string,
+  linkReplacer: GetRenderableContentByTypeName = linkFromTypeNameGenerator,
+  emailReplacer: GetRenderableContentByTypeName = defaultGetEmailByReference,
+): RenderableContent[] {
+  return replaceInlineEmails(replaceInlineLinks([text], linkReplacer), emailReplacer);
+}
+
+function replaceInlineLinks(
+  renderableContents: RenderableContent[],
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
+}
+
+function inlineLinkContent(
+  renderableContent: RenderableContent,
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  const text = renderableContent;
+
+  // Matches either `<<ClassName>>` or `{@link ClassName}`
+  const linkFormatRegEx = '{@link (.*?)}|<<([^>]+)>>';
+  const matches = match(linkFormatRegEx, text);
+  return createRenderableContents(matches, text, getLinkByTypeName);
+}
+
+export function replaceInlineEmails(
+  renderableContents: RenderableContent[],
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
+}
+
+function inlineEmailContent(
+  renderableContent: RenderableContent,
+  getLinkByTypeName: GetRenderableContentByTypeName,
+): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  const text = renderableContent;
+
+  // Parsing references using the format '{@email email}'
+  const linkFormatRegEx = '{@email (.*?)}';
+  const matches = match(linkFormatRegEx, text);
+  return createRenderableContents(matches, text, getLinkByTypeName);
+}
+
+function match(regex: string, text: string) {
+  const expression = new RegExp(regex, 'gi');
+  let match;
+  const matches = [];
+
+  do {
+    match = expression.exec(text);
+    if (match) {
+      matches.push(match);
+    }
+  } while (match);
+
+  return matches;
+}
+
+function createRenderableContents(matches: RegExpExecArray[], text: string, linker: GetRenderableContentByTypeName) {
+  if (matches.length === 0) {
+    return [text];
+  }
+
+  const result: RenderableContent[] = [];
+  let lastIndex = 0;
+  for (const match of matches) {
+    const index = match.index;
+    const length = match[0].length;
+
+    // loop through the matches (skip the first one, which is the full match)
+    // until we find the first capturing group that has a value
+    const capturedGroup = match.slice(1).find((group) => group);
+    if (!capturedGroup) {
+      continue;
+    }
+    result.push(text.slice(lastIndex, index));
+    result.push(linker(capturedGroup));
+
+    lastIndex = index + length;
+  }
+
+  if (lastIndex < text.length) {
+    result.push(text.slice(lastIndex));
+  }
+
+  return result;
+}

package/src/adapters/type-utils.ts

@@ -0,0 +1,5 @@
+import { EmptyLine, RenderableContent } from '../templating/types';
+
+export function isEmptyLine(content: RenderableContent): content is EmptyLine {
+  return Object.keys(content).includes('type') && (content as { type: string }).type === 'empty-line';
+}

package/src/adapters/types.d.ts

@@ -0,0 +1,8 @@
+import { Annotation, DocComment } from '@cparra/apex-reflection';
+
+export type Describable = string[] | undefined;
+
+export type Documentable = {
+  annotations: Annotation[];
+  docComment?: DocComment;
+};

package/src/cli/generate.ts

@@ -126,6 +126,9 @@ result.then((config) => {
     onAfterProcess: config?.config?.onAfterProcess,
     onBeforeFileWrite: config?.config?.onBeforeFileWrite,
     frontMatterHeader: config?.config?.frontMatterHeader,
+    singleFile: config?.config?.singleFile,
+    fileName: config?.config?.fileName,
+    templateFilePath: config?.config?.templateFilePath,
   });
 
   try {

package/src/model/__tests__/manifest.spec.ts

@@ -6,6 +6,7 @@ const sampleEnum: EnumMirror = {
   name: 'SampleEnum',
   type_name: 'enum',
   access_modifier: 'public',
+  values: [],
 };
 
 it('holds a list of types', () => {

package/src/model/manifest.ts

@@ -38,7 +38,7 @@ export default class Manifest {
         properties: this.filterAccessibleModifier(currentClass.properties, modifiers),
         fields: this.filterAccessibleModifier(currentClass.fields, modifiers),
         constructors: this.filterAccessibleModifier(currentClass.constructors, modifiers),
-      };
+      } as ClassMirror;
 
       if (!this.isForInnerTypes) {
         filteredClass = {
@@ -57,8 +57,8 @@ export default class Manifest {
     return typesToReturn;
   }
 
-  filterAccessibleModifier(accessAndDocAwares: AccessAndDocAware[], modifiers: string[]) {
-    return accessAndDocAwares.filter((currentType) => {
+  filterAccessibleModifier(accessAndDocAware: AccessAndDocAware[], modifiers: string[]) {
+    return accessAndDocAware.filter((currentType) => {
       const hasIgnoreDocAnnotation = currentType.docComment?.annotations.some(
         (annotation: DocCommentAnnotation) => annotation.name === 'ignore',
       );

package/src/model/markdown-file.ts

@@ -48,7 +48,7 @@ export class MarkdownFile extends OutputFile {
     });
     this.addBlankLine();
     this._contents += '|';
-    headers.forEach((_) => {
+    headers.forEach(() => {
       this._contents += '---' + '|';
     });
     this.addBlankLine();

package/src/model/openapi/open-api-types.ts

@@ -56,14 +56,14 @@ export type RequestBodyContent = {
 
 export type MediaTypeObject = {
   schema?: SchemaObject;
-  example?: any;
+  example?: unknown;
   examples?: { [index: string]: ExampleObject };
 };
 
 export type ExampleObject = {
   summary?: string;
   description?: string;
-  value?: any;
+  value?: unknown;
 };
 
 // Responses

package/src/service/__tests__/apex-file-reader.spec.ts

@@ -45,16 +45,16 @@ describe('File Reader', () => {
 
   it('returns an empty list when there are no Apex files in the directory', () => {
     const result = ApexFileReader.processFiles({
-      isDirectory(_: string): boolean {
+      isDirectory(): boolean {
         return false;
       },
-      joinPath(_: string): string {
+      joinPath(): string {
         return '';
       },
-      readDirectory(_: string): string[] {
+      readDirectory(): string[] {
         return ['SomeFile.md'];
       },
-      readFile(_: string): string {
+      readFile(): string {
         return '';
       },
       exists(): boolean {

package/src/service/__tests__/manifest-factory.spec.ts

@@ -1,7 +1,6 @@
 import { createManifest } from '../manifest-factory';
 import { Type } from '@cparra/apex-reflection';
 import { TypeParser } from '../parser';
-import ApexBundle from '../../model/apex-bundle';
 
 class TestParser implements TypeParser {
   parse(): Type[] {
@@ -10,7 +9,7 @@ class TestParser implements TypeParser {
 }
 
 it('creates a manifest from the result of a type parser', () => {
-  const manifest = createManifest(new TestParser(), (bundle: ApexBundle) => {
+  const manifest = createManifest(new TestParser(), () => {
     return {};
   });
   expect(manifest.types.length).toBe(0);

package/src/settings.ts

@@ -40,6 +40,9 @@ export interface SettingsConfig {
   onAfterProcess?: (files: TargetFile[]) => void;
   onBeforeFileWrite?: (file: TargetFile) => TargetFile;
   frontMatterHeader?: (file: TargetType) => string[];
+  singleFile?: boolean;
+  fileName?: string;
+  templateFilePath?: string;
 }
 
 export class Settings {
@@ -144,4 +147,16 @@ export class Settings {
     }
     return [];
   }
+
+  public shouldOutputSingleFile(): boolean {
+    return this.config.singleFile ?? false;
+  }
+
+  public getSingleFileName(): string {
+    return this.config.fileName ?? 'README';
+  }
+
+  public getTemplateFilePath(): string | undefined {
+    return this.config.templateFilePath;
+  }
 }