@cparra/apexdocs 2.25.0-alpha.0 → 2.25.0-alpha.1

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

@@ -0,0 +1,131 @@
+export type Link = {
+  title: string;
+  url: string;
+};
+
+export type EmptyLine = {
+  type: 'empty-line';
+};
+
+export type StringOrLink = string | Link;
+
+export type RenderableContent = StringOrLink | EmptyLine;
+
+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 RenderableDocumentation = {
+  annotations?: Annotation[];
+  description?: RenderableContent[];
+  customTags?: CustomTag[];
+  mermaid: RenderableSection<CodeBlock | undefined>;
+  example: RenderableSection<CodeBlock | undefined>;
+  group?: string;
+  author?: string;
+  date?: string;
+  sees?: StringOrLink[];
+};
+
+type RenderableType = {
+  namespace?: string;
+  headingLevel: number;
+  heading: string;
+  name: string;
+  meta: {
+    accessModifier: string;
+  };
+  doc: RenderableDocumentation;
+};
+
+type RenderableMethodParameter = {
+  name: string;
+  type: StringOrLink;
+  description?: RenderableContent[];
+};
+
+type TypeSource = {
+  type: StringOrLink;
+  description?: RenderableContent[];
+};
+
+type RenderableConstructor = {
+  headingLevel: number;
+  heading: string;
+  signature: RenderableSection<CodeBlock>;
+  parameters?: RenderableSection<RenderableMethodParameter[] | undefined>;
+  throws?: RenderableSection<TypeSource[] | undefined>;
+  doc: RenderableDocumentation;
+};
+
+type RenderableMethod = {
+  doc: RenderableDocumentation;
+  headingLevel: number;
+  heading: string;
+  signature: RenderableSection<CodeBlock>;
+  parameters: RenderableSection<RenderableMethodParameter[] | undefined>;
+  returnType: RenderableSection<TypeSource>;
+  throws: RenderableSection<TypeSource[] | undefined>;
+  inherited?: boolean;
+};
+
+type RenderableField = {
+  headingLevel: number;
+  heading: string;
+  type: RenderableSection<StringOrLink>;
+  accessModifier: string;
+  inherited?: boolean;
+  signature: RenderableSection<CodeBlock>;
+  doc: RenderableDocumentation;
+};
+
+export type RenderableSection<T> = {
+  headingLevel: number;
+  heading: string;
+  value: T;
+};
+
+export type GroupedMember<T> = RenderableSection<T[]> & { groupDescription: string | undefined };
+
+export type RenderableClass = RenderableType & {
+  type: 'class';
+  extends?: StringOrLink;
+  implements?: StringOrLink[];
+  classModifier?: string;
+  sharingModifier?: string;
+  constructors: RenderableSection<RenderableConstructor[] | GroupedMember<RenderableConstructor>[]> & {
+    isGrouped: boolean;
+  };
+  methods: RenderableSection<RenderableMethod[] | GroupedMember<RenderableMethod>[]> & { isGrouped: boolean };
+  fields: RenderableSection<RenderableField[] | GroupedMember<RenderableField>[]> & { isGrouped: boolean };
+  properties: RenderableSection<RenderableField[] | GroupedMember<RenderableField>[]> & { isGrouped: boolean };
+  innerClasses: RenderableSection<RenderableClass[]>;
+  innerEnums: RenderableSection<RenderableEnum[]>;
+  innerInterfaces: RenderableSection<RenderableInterface[]>;
+};
+
+export type RenderableInterface = RenderableType & {
+  type: 'interface';
+  extends?: StringOrLink[];
+  methods: RenderableSection<RenderableMethod[]>;
+};
+
+export type RenderableEnum = RenderableType & {
+  type: 'enum';
+  values: RenderableSection<EnumValue[]>;
+};
+
+export type Renderable = RenderableClass | RenderableInterface | RenderableEnum;

package/src/core/template.ts

@@ -0,0 +1,108 @@
+import Handlebars from 'handlebars';
+import { typeDocPartial } from '../transpiler/markdown/plain-markdown/type-doc-partial';
+import { documentablePartialTemplate } from '../transpiler/markdown/plain-markdown/documentable-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 { classMarkdownTemplate } from '../transpiler/markdown/plain-markdown/class-template';
+import { enumMarkdownTemplate } from '../transpiler/markdown/plain-markdown/enum-template';
+import { interfaceMarkdownTemplate } from '../transpiler/markdown/plain-markdown/interface-template';
+import { RenderableContent, StringOrLink } from './renderable/types';
+import { isEmptyLine } from '../adapters/type-utils';
+import { groupedMembersPartialTemplate } from '../transpiler/markdown/plain-markdown/grouped-members-partial-template';
+
+export type CompilationRequest = {
+  template: string;
+  source: unknown;
+};
+
+export class Template {
+  private static instance: Template;
+
+  private constructor() {
+    Handlebars.registerPartial('typeDocumentation', typeDocPartial);
+    Handlebars.registerPartial('documentablePartialTemplate', documentablePartialTemplate);
+    Handlebars.registerPartial('methodsPartialTemplate', methodsPartialTemplate);
+    Handlebars.registerPartial('constructorsPartialTemplate', constructorsPartialTemplate);
+    Handlebars.registerPartial('groupedMembersPartialTemplate', groupedMembersPartialTemplate);
+    Handlebars.registerPartial('fieldsPartialTemplate', fieldsPartialTemplate);
+    Handlebars.registerPartial('classTemplate', classMarkdownTemplate);
+    Handlebars.registerPartial('enumTemplate', enumMarkdownTemplate);
+    Handlebars.registerPartial('interfaceTemplate', interfaceMarkdownTemplate);
+
+    Handlebars.registerHelper('link', link);
+    Handlebars.registerHelper('code', convertCodeBlock);
+    Handlebars.registerHelper('withLinks', resolveLinksInContent);
+    Handlebars.registerHelper('heading', heading);
+    Handlebars.registerHelper('inlineCode', inlineCode);
+    Handlebars.registerHelper('splitAndCapitalize', splitAndCapitalize);
+  }
+
+  public static getInstance(): Template {
+    if (!Template.instance) {
+      Template.instance = new Template();
+    }
+    return Template.instance;
+  }
+
+  compile(request: CompilationRequest): string {
+    const compiled = Handlebars.compile(request.template);
+    return (
+      compiled(request.source)
+        .trim()
+        // clean up extra newlines
+        .replace(/\n{3,}/g, '\n\n')
+    );
+  }
+}
+
+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(' ');
+};
+
+const heading = (level: number, text: string) => {
+  return `${'#'.repeat(level)} ${text}`;
+};
+
+const inlineCode = (text: string) => {
+  return new Handlebars.SafeString(`\`${text}\``);
+};
+
+const convertCodeBlock = (language: string, lines: string[]): Handlebars.SafeString => {
+  return new Handlebars.SafeString(
+    `
+\`\`\`${language}
+${lines.join('\n')}
+\`\`\`
+  `.trim(),
+  );
+};
+
+const resolveLinksInContent = (description?: RenderableContent[]): string => {
+  if (!description) {
+    return '';
+  }
+
+  function reduceDescription(acc: string, curr: RenderableContent) {
+    if (isEmptyLine(curr)) {
+      return acc + '\n\n';
+    }
+
+    return acc + link(curr).trim() + ' ';
+  }
+
+  return description.reduce(reduceDescription, '').trim();
+};
+
+const link = (source: StringOrLink): string => {
+  if (typeof source === 'string') {
+    return source;
+  } else {
+    return `[${source.title}](${source.url})`;
+  }
+};

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

@@ -0,0 +1,14 @@
+export const referenceGuideTemplate = `
+# Apex Reference Guide
+
+{{#each this}}
+## {{@key}}
+
+{{#each this}}
+### {{link title}}
+
+{{withLinks description}}
+
+{{/each}}
+{{/each}}
+`.trim();

package/src/index.ts

@@ -1 +1,3 @@
-export * from './service/manifest-factory';
+import * as reflection from '@cparra/apex-reflection';
+
+export { reflection };

package/src/model/manifest.ts

@@ -26,11 +26,21 @@ export default class Manifest {
     const typesToReturn: Type[] = [];
     for (const filteredType of filteredTypes) {
       const currentType = filteredType as Type;
-      if (currentType.type_name !== 'class') {
+      if (currentType.type_name === 'enum') {
+        // Ignoring enum values is not supported.
         typesToReturn.push(currentType);
         continue;
       }
 
+      if (currentType.type_name === 'interface') {
+        const currentInterface = currentType as InterfaceMirror;
+        typesToReturn.push({
+          ...currentType,
+          methods: this.filterAccessibleModifier(currentInterface.methods, modifiers),
+        } as InterfaceMirror);
+        continue;
+      }
+
       const currentClass = currentType as ClassMirror;
       let filteredClass = {
         ...currentType,
@@ -60,7 +70,7 @@ export default class Manifest {
   filterAccessibleModifier(accessAndDocAware: AccessAndDocAware[], modifiers: string[]) {
     return accessAndDocAware.filter((currentType) => {
       const hasIgnoreDocAnnotation = currentType.docComment?.annotations.some(
-        (annotation: DocCommentAnnotation) => annotation.name === 'ignore',
+        (annotation: DocCommentAnnotation) => annotation.name.toLowerCase() === 'ignore',
       );
       if (hasIgnoreDocAnnotation) {
         return false;

package/src/model/markdown-file.ts

@@ -18,12 +18,13 @@ export class MarkdownFile extends OutputFile {
     this.addBlankLine();
   }
 
-  public addText(text: string, encodeHtml = true) {
-    super.addText(this._replaceInlineReferences(text), encodeHtml);
+  public addText(text: string) {
+    //super.addText(this._replaceInlineReferences(text), encodeHtml);
+    super.addText(text);
   }
 
-  public addLink(text: string, encodeHtml = true) {
-    this.addText(`\{@link ${text}\}`, encodeHtml);
+  public addLink(text: string) {
+    this.addText(`{@link ${text}}`);
   }
 
   startCodeBlock(language = 'apex') {

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

@@ -15,7 +15,7 @@ export function addMermaid(markdownFile: MarkdownFile, docCommentAware: DocComme
   markdownFile.addBlankLine();
   markdownFile.startCodeBlock('mermaid');
   mermaid.bodyLines.forEach((line) => {
-    markdownFile.addText(line, false);
+    markdownFile.addText(line);
   });
   markdownFile.endCodeBlock();
   markdownFile.addBlankLine();

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

@@ -153,7 +153,7 @@ function addExample(markdownFile: MarkdownFile, docCommentAware: DocCommentAware
   markdownFile.addTitle('Example', startingHeadingLevel + 3);
   markdownFile.startCodeBlock();
   docCommentAware.docComment?.exampleAnnotation.bodyLines.forEach((line) => {
-    markdownFile.addText(line, false);
+    markdownFile.addText(line);
   });
   markdownFile.endCodeBlock();
   markdownFile.addBlankLine();

package/src/model/outputFile.ts

@@ -1,10 +1,3 @@
-import xss = require('xss');
-import { Settings } from '../settings';
-
-const xssFilter = new xss.FilterXSS({
-  whiteList: { br: [], p: [], ul: [], li: [], code: [], pre: [] },
-});
-
 export abstract class OutputFile {
   _contents = '';
 
@@ -16,10 +9,8 @@ export abstract class OutputFile {
     return this._contents;
   }
 
-  addText(text: string, encodeHtml = true) {
-    const shouldEncode = encodeHtml && Settings.getInstance().sanitizeHtml;
-    const textToAdd = shouldEncode ? xssFilter.process(text) : text;
-    this._contents += textToAdd;
+  addText(text: string) {
+    this._contents += text;
     this.addBlankLine();
   }
 

package/src/service/parser.ts

@@ -60,7 +60,7 @@ export class RawBodyParser implements TypeParser {
         continue;
       }
 
-      // If reaching here then we are dealing with an interface
+      // At this stage, we can be sure we are dealing with an interface
       let typeAsInterface = currentType as InterfaceMirror;
       if (!typeAsInterface.extended_interfaces.length) {
         typesWithFields.push(currentType);

package/src/settings.ts

@@ -40,9 +40,6 @@ export interface SettingsConfig {
   onAfterProcess?: (files: TargetFile[]) => void;
   onBeforeFileWrite?: (file: TargetFile) => TargetFile;
   frontMatterHeader?: (file: TargetType) => string[];
-  singleFile?: boolean;
-  fileName?: string;
-  templateFilePath?: string;
 }
 
 export class Settings {
@@ -147,16 +144,4 @@ 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;
-  }
 }

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

@@ -3,7 +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';
+import { StringOrLink } from '../../core/renderable/types';
 
 export default class ClassFileGeneratorHelper {
   public static getSanitizedGroup(classModel: Type) {

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

@@ -1,32 +1,73 @@
 export const classMarkdownTemplate = `
-# {{name}} Class
+{{ heading headingLevel heading }}
 {{#if classModifier}}
 \`{{classModifier}}\`
 {{/if}}
 
-{{> typeLevelApexDocPartialTemplate}}
+{{> typeDocumentation}}
 
 {{#if extends}}
 **Extends**
-{{extends}}
+{{link extends}}
 {{/if}}
 
 {{#if implements}}
 **Implements**
 {{#each implements}}
-{{this}}{{#unless @last}}, {{/unless}}
+{{link this}}{{#unless @last}}, {{/unless}}
 {{/each}}
 {{/if}}
 
-{{#if fields}}
-{{> fieldsPartialTemplate}}
+{{#if fields.value}}
+{{#if fields.isGrouped}}
+{{> groupedMembersPartialTemplate fields subTemplate="fieldsPartialTemplate"}}
+{{else}}
+{{> fieldsPartialTemplate fields}}
+{{/if}}
+{{/if}}
+
+{{#if properties.value}}
+{{#if properties.isGrouped}}
+{{> groupedMembersPartialTemplate properties subTemplate="fieldsPartialTemplate"}}
+{{else}}
+{{> fieldsPartialTemplate properties}}
+{{/if}}
 {{/if}}
 
-{{#if constructors}}
-{{> constructorsPartialTemplate}}
+{{#if constructors.value}}
+{{#if constructors.isGrouped}}
+{{> groupedMembersPartialTemplate constructors subTemplate="constructorsPartialTemplate"}}
+{{else}}
+{{> constructorsPartialTemplate constructors}}
+{{/if}}
+{{/if}}
+
+{{#if methods.value}}
+{{#if methods.isGrouped}}
+{{> groupedMembersPartialTemplate methods subTemplate="methodsPartialTemplate"}}
+{{else}}
+{{> methodsPartialTemplate methods}}
+{{/if}}
 {{/if}}
 
-{{#if methods}}
-{{> methodsPartialTemplate}}
+{{#if innerClasses.value}}
+{{ heading innerClasses.headingLevel innerClasses.heading }}
+{{#each innerClasses.value}}
+{{> classTemplate this}}
+{{/each}}
+{{/if}}
+
+{{#if innerEnums.value}}
+{{ heading innerEnums.headingLevel innerEnums.heading }}
+{{#each innerEnums.value}}
+{{> enumTemplate this}}
+{{/each}}
+{{/if}}
+
+{{#if innerInterfaces.value}}
+{{ heading innerInterfaces.headingLevel innerInterfaces.heading }}
+{{#each innerInterfaces.value}}
+{{> interfaceTemplate this}}
+{{/each}}
 {{/if}}
 `.trim();

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

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

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

@@ -1,21 +1,24 @@
 export const documentablePartialTemplate = `
-{{#each annotations}}
+{{#each doc.annotations}}
 \`{{this}}\`
 {{/each}}
 
-{{description}}
+{{withLinks doc.description}}
 
-{{#each customTags}}
-**{{splitAndCapitalize name}}** {{description}}
+{{#each doc.customTags}}
+**{{splitAndCapitalize name}}** {{withLinks description}}
 
 {{/each}}
 
 {{> @partial-block}}
 
-{{{mermaid}}}
+{{#if doc.mermaid.value}}
+{{ heading doc.mermaid.headingLevel doc.mermaid.heading }}
+{{code "mermaid" doc.mermaid.value}}
+{{/if}}
 
-{{#if example}}
-##{{#if isInner}}#{{/if}} Example
-{{{example}}}
+{{#if doc.example.value}}
+{{ heading doc.example.headingLevel doc.example.heading }}
+{{code "apex" doc.example.value}}
 {{/if}}
 `.trim();

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

@@ -1,11 +1,12 @@
 export const enumMarkdownTemplate = `
-# {{name}} Enum
+{{ heading headingLevel heading }}
 
-{{> typeLevelApexDocPartialTemplate}}
+{{> typeDocumentation }}
 
-## Enum Values
-{{#each values}}
-### {{value}}
-{{description}}
+{{ heading values.headingLevel values.heading }}
+| Value | Description |
+|-------|-------------|
+{{#each values.value}}
+| {{value}} | {{description}} |
 {{/each}}
 `.trim();

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

@@ -1,16 +1,19 @@
 export const fieldsPartialTemplate = `
-## Fields
-{{#each fields}}
-### \`\{{name}}\`
+{{ heading headingLevel heading }}
+{{#each value}}
+{{{ heading headingLevel (inlineCode heading) }}}
 
 {{#if inherited}}
 *Inherited*
 {{/if}}
 
-{{#> documentablePartialTemplate}}
+{{#> documentablePartialTemplate }}
 
-#### Type
-{{type}}
+{{ heading signature.headingLevel signature.heading }}
+{{ code "apex" signature.value }}
+
+{{ heading type.headingLevel type.heading }}
+{{link type.value}}
 
 {{/documentablePartialTemplate}}
 

package/src/transpiler/markdown/plain-markdown/grouped-members-partial-template.ts

@@ -0,0 +1,6 @@
+export const groupedMembersPartialTemplate = `
+{{ heading headingLevel heading }}
+{{#each value}}
+{{> (lookup .. "subTemplate") this}}
+{{/each}}
+`.trim();

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

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