@cparra/apexdocs 2.23.0 → 2.25.0-alpha.0

package/src/templating/compile.ts

@@ -0,0 +1,187 @@
+import Handlebars from 'handlebars';
+import {
+  EnumSource,
+  ConvertRenderableContentsToString,
+  InterfaceSource,
+  ClassSource,
+  MethodSource,
+  RenderableContent,
+  DocumentableSource,
+} from './types';
+import { namespace, splitAndCapitalize } from './helpers';
+import { typeLevelApexDocPartialTemplate } from '../transpiler/markdown/plain-markdown/type-level-apex-doc-partial-template';
+import { methodsPartialTemplate } from '../transpiler/markdown/plain-markdown/methods-partial-template';
+import { constructorsPartialTemplate } from '../transpiler/markdown/plain-markdown/constructors-partial-template';
+import { fieldsPartialTemplate } from '../transpiler/markdown/plain-markdown/fieldsPartialTemplate';
+import { documentablePartialTemplate } from '../transpiler/markdown/plain-markdown/documentable-partial-template';
+
+type CompileOptions = {
+  renderableContentConverter: ConvertRenderableContentsToString;
+  codeBlockConverter: (language: string, lines: string[]) => string;
+};
+
+export function compile(template: string, source: EnumSource | InterfaceSource | ClassSource, options: CompileOptions) {
+  Handlebars.registerPartial('typeLevelApexDocPartialTemplate', typeLevelApexDocPartialTemplate);
+  Handlebars.registerPartial('documentablePartialTemplate', documentablePartialTemplate);
+  Handlebars.registerPartial('methodsPartialTemplate', methodsPartialTemplate);
+  Handlebars.registerPartial('constructorsPartialTemplate', constructorsPartialTemplate);
+  Handlebars.registerPartial('fieldsPartialTemplate', fieldsPartialTemplate);
+
+  Handlebars.registerHelper('splitAndCapitalize', splitAndCapitalize);
+
+  const prepared = { ...prepare(source, options), namespace: namespace() };
+  const compiled = Handlebars.compile(template);
+  return (
+    compiled(prepared)
+      .trim()
+      // clean up extra newlines
+      .replace(/\n{3,}/g, '\n\n')
+  );
+}
+
+function prepare(
+  source: EnumSource | InterfaceSource | ClassSource,
+  { renderableContentConverter, codeBlockConverter }: CompileOptions,
+) {
+  const base = {
+    ...source,
+    ...prepareDocumentable(source, renderableContentConverter, codeBlockConverter),
+    ...prepareBaseType(source, renderableContentConverter),
+  };
+  if (isEnumSource(source)) {
+    return {
+      ...base,
+      ...prepareEnum(source, renderableContentConverter),
+    };
+  } else if (isInterfaceSource(source)) {
+    return {
+      ...base,
+      ...prepareInterface(source, renderableContentConverter, codeBlockConverter),
+    };
+  } else {
+    return {
+      ...base,
+      ...prepareClass(source, renderableContentConverter, codeBlockConverter),
+    };
+  }
+}
+
+function prepareDocumentable(
+  source: DocumentableSource,
+  renderableContentConverter: ConvertRenderableContentsToString,
+  codeBlockConverter: (language: string, lines: string[]) => string,
+) {
+  return {
+    description: renderableContentConverter(source.description),
+    mermaid: source.mermaid ? codeBlockConverter('mermaid', source.mermaid) : undefined,
+    example: source.example ? codeBlockConverter('apex', source.example) : undefined,
+    customTags: source.customTags?.map((tag) => ({
+      name: tag.name,
+      value: renderableContentConverter(tag.description),
+    })),
+  };
+}
+
+function prepareBaseType(
+  source: EnumSource | InterfaceSource | ClassSource,
+  renderableContentConverter: ConvertRenderableContentsToString,
+) {
+  return {
+    sees: source.sees?.map((see) => renderableContentConverter([see])),
+  };
+}
+
+function prepareEnum(source: EnumSource, renderableContentConverter: ConvertRenderableContentsToString) {
+  return {
+    values: source.values.map((value) => ({
+      value: value.value,
+      description: renderableContentConverter(value.description),
+    })),
+  };
+}
+
+function prepareInterface(
+  source: InterfaceSource,
+  renderableContentConverter: ConvertRenderableContentsToString,
+  codeBlockConverter: (language: string, lines: string[]) => string,
+) {
+  return {
+    extends: source.extends?.map((ext) => renderableContentConverter([ext])),
+    methods: source.methods?.map((method) => mapMethod(method, renderableContentConverter, codeBlockConverter)),
+  };
+}
+
+function prepareClass(
+  source: ClassSource,
+  renderableContentConverter: ConvertRenderableContentsToString,
+  codeBlockConverter: (language: string, lines: string[]) => string,
+) {
+  return {
+    implements: source.implements?.map((impl) => renderableContentConverter([impl])),
+    extends: source.extends ? renderableContentConverter([source.extends]) : undefined,
+    constructors: source.constructors?.map((constructor) =>
+      mapConstructor(constructor, renderableContentConverter, codeBlockConverter),
+    ),
+    methods: source.methods?.map((method) => mapMethod(method, renderableContentConverter, codeBlockConverter)),
+    fields: source.fields?.map((field) => ({
+      ...field,
+      ...prepareDocumentable(field, renderableContentConverter, codeBlockConverter),
+      type: renderableContentConverter([field.type]),
+    })),
+  };
+}
+
+function mapMethod(
+  method: MethodSource,
+  renderableContentConverter: (content?: RenderableContent[]) => string,
+  codeBlockConverter: (language: string, lines: string[]) => string,
+) {
+  return {
+    ...method,
+    ...prepareDocumentable(method, renderableContentConverter, codeBlockConverter),
+    returnType: {
+      ...method,
+      type: method.returnType?.type ? renderableContentConverter([method.returnType.type]) : undefined,
+      description: renderableContentConverter(method.returnType?.description),
+    },
+    throws: method.throws?.map((thrown) => ({
+      ...thrown,
+      type: renderableContentConverter([thrown.type]),
+      description: renderableContentConverter(thrown.description),
+    })),
+    parameters: method.parameters?.map((param) => ({
+      ...param,
+      type: renderableContentConverter([param.type]),
+      description: renderableContentConverter(param.description),
+    })),
+  };
+}
+
+function mapConstructor(
+  constructor: MethodSource,
+  renderableContentConverter: (content?: RenderableContent[]) => string,
+  codeBlockConverter: (language: string, lines: string[]) => string,
+) {
+  return {
+    ...constructor,
+    ...prepareDocumentable(constructor, renderableContentConverter, codeBlockConverter),
+    parameters: constructor.parameters?.map((param) => ({
+      ...param,
+      type: renderableContentConverter([param.type]),
+      description: renderableContentConverter(param.description),
+    })),
+    throws: constructor.throws?.map((thrown) => ({
+      ...thrown,
+      type: renderableContentConverter([thrown.type]),
+      description: renderableContentConverter(thrown.description),
+    })),
+  };
+}
+
+function isEnumSource(source: { __type: string }): source is EnumSource {
+  return source.__type === 'enum';
+}
+
+function isInterfaceSource(source: { __type: string }): source is InterfaceSource {
+  return source.__type === 'interface';
+}

package/src/templating/helpers.ts

@@ -0,0 +1,14 @@
+import { Settings } from '../settings';
+
+export const 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(' ');
+};
+
+export const namespace = () => {
+  return Settings.getInstance().getNamespace();
+};

package/src/templating/types.d.ts

@@ -0,0 +1,104 @@
+export type Link = {
+  title: string;
+  url: string;
+};
+
+export type EmptyLine = {
+  type: 'empty-line';
+};
+
+export type StringOrLink = string | Link;
+
+export type RenderableContent = StringOrLink | EmptyLine;
+
+export type ConvertRenderableContentsToString = (content?: RenderableContent[]) => string;
+
+type EnumValue = {
+  value: string;
+  description?: RenderableContent[];
+};
+
+type CustomTag = {
+  name: string;
+  description?: RenderableContent[];
+};
+
+/**
+ * Represents an annotation to a top-level type. For example @NamespaceAccessible.
+ */
+type Annotation = string;
+
+type CodeBlock = string[];
+
+type DocumentableSource = {
+  annotations?: Annotation[];
+  description?: RenderableContent[];
+  customTags?: CustomTag[];
+  mermaid?: CodeBlock;
+  example?: CodeBlock;
+};
+
+type BaseTypeSource = DocumentableSource & {
+  name: string;
+  accessModifier: string;
+  group?: string;
+  author?: string;
+  date?: string;
+  sees?: StringOrLink[];
+};
+
+type MethodParameterSource = {
+  name: string;
+  type: StringOrLink;
+  description?: RenderableContent[];
+};
+
+type TypeSource = {
+  type: StringOrLink;
+  description?: RenderableContent[];
+};
+
+type ConstructorSource = DocumentableSource & {
+  title: string;
+  signature: string;
+  parameters?: MethodParameterSource[];
+  throws?: TypeSource[];
+};
+
+type MethodSource = DocumentableSource & {
+  title: string;
+  signature: string;
+  parameters?: MethodParameterSource[];
+  returnType?: TypeSource;
+  throws?: TypeSource[];
+  inherited?: boolean;
+};
+
+type FieldSource = DocumentableSource & {
+  name: string;
+  type: StringOrLink;
+  accessModifier: string;
+  inherited?: boolean;
+};
+
+export type ClassSource = BaseTypeSource & {
+  __type: 'class';
+  extends?: StringOrLink;
+  implements?: StringOrLink[];
+  constructors?: ConstructorSource[];
+  methods?: MethodSource[];
+  classModifier?: string;
+  sharingModifier?: string;
+  fields?: FieldSource[];
+};
+
+export type InterfaceSource = BaseTypeSource & {
+  __type: 'interface';
+  extends?: StringOrLink[];
+  methods?: MethodSource[];
+};
+
+export type EnumSource = BaseTypeSource & {
+  __type: 'enum';
+  values: EnumValue[];
+};

package/src/test-helpers/FieldMirrorBuilder.ts

@@ -1,5 +1,5 @@
 import { DocComment, FieldMirror } from '@cparra/apex-reflection';
-import { ReferencedType } from '@cparra/apex-reflection/index';
+import { ReferencedType } from '@cparra/apex-reflection';
 
 type MemberModifier = 'static' | 'webservice' | 'final' | 'override' | 'testmethod' | 'transient';
 

package/src/test-helpers/InterfaceMirrorBuilder.ts

@@ -0,0 +1,44 @@
+import { Annotation, DocComment, InterfaceMirror, MethodMirror } from '@cparra/apex-reflection';
+
+/**
+ * Builder class to create Interface objects.
+ * For testing purposes only.
+ */
+export class InterfaceMirrorBuilder {
+  private name = 'SampleClass';
+  private annotations: Annotation[] = [];
+  private docComment?: DocComment;
+  private methods: MethodMirror[] = [];
+
+  withName(name: string): InterfaceMirrorBuilder {
+    this.name = name;
+    return this;
+  }
+
+  addAnnotation(annotation: Annotation): InterfaceMirrorBuilder {
+    this.annotations.push(annotation);
+    return this;
+  }
+
+  withDocComment(docComment: DocComment): InterfaceMirrorBuilder {
+    this.docComment = docComment;
+    return this;
+  }
+
+  addMethod(method: MethodMirror): InterfaceMirrorBuilder {
+    this.methods.push(method);
+    return this;
+  }
+
+  build(): InterfaceMirror {
+    return {
+      annotations: this.annotations,
+      name: this.name,
+      type_name: 'interface',
+      methods: this.methods,
+      access_modifier: 'public',
+      docComment: this.docComment,
+      extended_interfaces: [],
+    };
+  }
+}

package/src/test-helpers/MethodMirrorBuilder.ts

@@ -1,9 +1,16 @@
-import { Annotation, DocComment, MethodMirror } from '@cparra/apex-reflection';
+import { Annotation, DocComment, MethodMirror, ParameterMirror } from '@cparra/apex-reflection';
+
+type Parameter = ParameterMirror;
 
 export class MethodMirrorBuilder {
   private name = 'sampleMethod';
   private annotations: Annotation[] = [];
   private docComment?: DocComment;
+  private typeReference: { type: string; rawDeclaration: string } = {
+    type: 'void',
+    rawDeclaration: 'void',
+  };
+  private parameters: Parameter[] = [];
 
   withName(name: string): MethodMirrorBuilder {
     this.name = name;
@@ -20,18 +27,51 @@ export class MethodMirrorBuilder {
     return this;
   }
 
+  withTypeReference(param: { type: string; rawDeclaration: string }) {
+    this.typeReference = param;
+    return this;
+  }
+
+  addParameter(parameter: Parameter): MethodMirrorBuilder {
+    this.parameters.push(parameter);
+    return this;
+  }
+
   build(): MethodMirror {
     return {
       access_modifier: 'public',
       annotations: this.annotations,
       name: this.name,
       memberModifiers: [],
-      typeReference: {
-        type: 'void',
-        rawDeclaration: 'void',
-      },
-      parameters: [],
+      typeReference: this.typeReference,
+      parameters: this.parameters,
       docComment: this.docComment,
     };
   }
 }
+
+export class ParameterBuilder {
+  private name = 'param';
+  private typeReference: { type: string; rawDeclaration: string } = {
+    type: 'String',
+    rawDeclaration: 'String',
+  };
+
+  withName(name: string): ParameterBuilder {
+    this.name = name;
+    return this;
+  }
+
+  withTypeReference(param: { type: string; rawDeclaration: string }) {
+    this.typeReference = param;
+    return this;
+  }
+
+  build(): Parameter {
+    return {
+      memberModifiers: [],
+      name: this.name,
+      typeReference: this.typeReference,
+    };
+  }
+}

package/src/transpiler/markdown/class-file-generatorHelper.ts

@@ -3,6 +3,7 @@ import { TypesRepository } from '../../model/types-repository';
 import { Settings } from '../../settings';
 import State from '../../service/state';
 import { TypeTranspilerFactory } from '../factory';
+import { StringOrLink } from '../../templating/types';
 
 export default class ClassFileGeneratorHelper {
   public static getSanitizedGroup(classModel: Type) {
@@ -10,13 +11,18 @@ export default class ClassFileGeneratorHelper {
   }
 
   public static getFileLink(classModel: Type) {
+    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(classModel);
+    return `[${fullClassName}](${fileLink})`;
+  }
+
+  private static getFileLinkTuple(classModel: Type): [string, string] {
     const documentationRoot = Settings.getInstance().getRootDir() ?? '';
     const directoryRoot = `${documentationRoot}${this.getDirectoryRoot(classModel)}`;
     const fullClassName = `${Settings.getInstance().getNamespacePrefix()}${classModel.name}`;
-    return `[${fullClassName}](${directoryRoot}${fullClassName}.md)`;
+    return [fullClassName, `${directoryRoot}${fullClassName}.md`];
   }
 
-  public static getFileLinkByTypeName(typeName: string) {
+  public static getFileLinkByTypeName(typeName: string): string {
     const type = TypesRepository.getInstance().getFromScopedByName(typeName);
     if (!type) {
       // If the type is not found, we return a Markdown hyperlink with whatever we received.
@@ -26,6 +32,20 @@ export default class ClassFileGeneratorHelper {
     return this.getFileLink(type);
   }
 
+  public static getRenderableLinkByTypeName(typeName: string): StringOrLink {
+    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
+    if (!type) {
+      // If the type is not found, we return the type name as a string.
+      return typeName;
+    }
+
+    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(type);
+    return {
+      title: fullClassName,
+      url: fileLink,
+    };
+  }
+
   private static getDirectoryRoot(classModel: Type) {
     // root-relative links start from the root by using a leading '/'
     const generator = Settings.getInstance().targetGenerator;

package/src/transpiler/markdown/plain-markdown/class-template.ts

@@ -0,0 +1,32 @@
+export const classMarkdownTemplate = `
+# {{name}} Class
+{{#if classModifier}}
+\`{{classModifier}}\`
+{{/if}}
+
+{{> typeLevelApexDocPartialTemplate}}
+
+{{#if extends}}
+**Extends**
+{{extends}}
+{{/if}}
+
+{{#if implements}}
+**Implements**
+{{#each implements}}
+{{this}}{{#unless @last}}, {{/unless}}
+{{/each}}
+{{/if}}
+
+{{#if fields}}
+{{> fieldsPartialTemplate}}
+{{/if}}
+
+{{#if constructors}}
+{{> constructorsPartialTemplate}}
+{{/if}}
+
+{{#if methods}}
+{{> methodsPartialTemplate}}
+{{/if}}
+`.trim();

package/src/transpiler/markdown/plain-markdown/constructors-partial-template.ts

@@ -0,0 +1,35 @@
+export const constructorsPartialTemplate = `
+## Constructors
+{{#each constructors}}
+### \`{{title}}\`
+
+{{#> documentablePartialTemplate}}
+
+### Signature
+\`\`\`apex
+{{signature}}
+\`\`\` 
+
+{{#if parameters}}
+### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+{{#each parameters}}
+| {{name}} | {{type}} | {{description}} |
+{{/each}}
+{{/if}}
+
+{{#if throws}}
+### Throws
+{{#each throws}}
+{{this.type}}: {{this.description}}
+
+{{/each}}
+{{/if}}
+
+{{/documentablePartialTemplate}}
+
+{{#unless @last}}---{{/unless}}
+{{/each}}
+
+`.trim();

package/src/transpiler/markdown/plain-markdown/documentable-partial-template.ts

@@ -0,0 +1,21 @@
+export const documentablePartialTemplate = `
+{{#each annotations}}
+\`{{this}}\`
+{{/each}}
+
+{{description}}
+
+{{#each customTags}}
+**{{splitAndCapitalize name}}** {{description}}
+
+{{/each}}
+
+{{> @partial-block}}
+
+{{{mermaid}}}
+
+{{#if example}}
+##{{#if isInner}}#{{/if}} Example
+{{{example}}}
+{{/if}}
+`.trim();

package/src/transpiler/markdown/plain-markdown/enum-template.ts

@@ -0,0 +1,11 @@
+export const enumMarkdownTemplate = `
+# {{name}} Enum
+
+{{> typeLevelApexDocPartialTemplate}}
+
+## Enum Values
+{{#each values}}
+### {{value}}
+{{description}}
+{{/each}}
+`.trim();

package/src/transpiler/markdown/plain-markdown/fieldsPartialTemplate.ts

@@ -0,0 +1,20 @@
+export const fieldsPartialTemplate = `
+## Fields
+{{#each fields}}
+### \`\{{name}}\`
+
+{{#if inherited}}
+*Inherited*
+{{/if}}
+
+{{#> documentablePartialTemplate}}
+
+#### Type
+{{type}}
+
+{{/documentablePartialTemplate}}
+
+{{#unless @last}}---{{/unless}}
+
+{{/each}}
+`.trim();

package/src/transpiler/markdown/plain-markdown/interface-template.ts

@@ -0,0 +1,16 @@
+export const interfaceMarkdownTemplate = `
+# {{name}} Interface
+
+{{> typeLevelApexDocPartialTemplate}}
+
+{{#if extends}}
+**Extends**
+{{#each extends}}
+{{this}}{{#unless @last}}, {{/unless}}
+{{/each}}
+{{/if}}
+
+{{#if methods}}
+{{> methodsPartialTemplate}}
+{{/if}}
+`.trim();

package/src/transpiler/markdown/plain-markdown/methods-partial-template.ts

@@ -0,0 +1,45 @@
+export const methodsPartialTemplate = `
+## Methods
+{{#each methods}}
+### \`{{title}}\`
+
+{{#if inherited}}
+*Inherited*
+{{/if}}
+
+{{#> documentablePartialTemplate isInner=true}}
+
+### Signature
+\`\`\`apex
+{{signature}}
+\`\`\` 
+
+{{#if parameters}}
+### Parameters
+| Name | Type | Description |
+|------|------|-------------|
+{{#each parameters}}
+| {{name}} | {{type}} | {{description}} |
+{{/each}}
+{{/if}}
+
+{{#if returnType}}
+### Returns
+**{{returnType.type}}**
+
+{{returnType.description}}
+{{/if}}
+
+{{#if throws}}
+### Throws
+{{#each throws}}
+{{this.type}}: {{this.description}}
+
+{{/each}}
+{{/if}}
+{{/documentablePartialTemplate}}
+
+{{#unless @last}}---{{/unless}}
+
+{{/each}}
+`.trim();