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

package/src/core/markdown/adapters/documentables.ts

@@ -0,0 +1,116 @@
+import { CustomTag, RenderableDocumentation, RenderableContent } from './types';
+import { Describable, Documentable, GetRenderableContentByTypeName } from './types';
+import { replaceInlineReferences } from './inline';
+import { isEmptyLine } from './type-utils';
+
+export function adaptDescribable(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): {
+  description?: RenderableContent[];
+} {
+  return {
+    description: describableToRenderableContent(describable, linkGenerator),
+  };
+}
+
+export function describableToRenderableContent(
+  describable: Describable,
+  linkGenerator: GetRenderableContentByTypeName,
+): RenderableContent[] | undefined {
+  if (!describable) {
+    return;
+  }
+
+  let content: RenderableContent[] = [];
+  for (let i = 0; i < describable.length; i++) {
+    const line = describable[i];
+    // The language might or might not be present after ```
+    const codeBlockMatch = line.match(/^```([a-zA-Z]*)$/);
+    if (codeBlockMatch) {
+      // Check if the language is present, if not, fallback to "apex"
+      const language = codeBlockMatch[1] || 'apex';
+      const codeBlockLines: string[] = [];
+      i++;
+      while (i < describable.length) {
+        const currentLine = describable[i];
+        if (currentLine.trim() === '```') {
+          break;
+        }
+        codeBlockLines.push(currentLine);
+        i++;
+      }
+      content = [
+        ...content,
+        {
+          __type: 'code-block',
+          language,
+          content: codeBlockLines,
+        },
+        { __type: 'empty-line' },
+      ];
+      continue;
+    }
+
+    content = [
+      ...content,
+      ...replaceInlineReferences(line, linkGenerator),
+      {
+        __type: 'empty-line',
+      },
+    ];
+  }
+  return (
+    content
+      // If the last element is an empty line, remove it
+      .filter((line, index, lines) => !(isEmptyLine(line) && index === lines.length - 1))
+  );
+}
+
+export function adaptDocumentable(
+  documentable: Documentable,
+  linkGenerator: GetRenderableContentByTypeName,
+  subHeadingLevel: number,
+): RenderableDocumentation {
+  function extractCustomTags(type: Documentable): CustomTag[] {
+    const baseTags = ['description', 'group', 'author', 'date', 'see', 'example', 'throws', 'exception'];
+
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => !baseTags.includes(currentAnnotation.name.toLowerCase()))
+        .map<CustomTag>((currentAnnotation) => ({
+          ...adaptDescribable(currentAnnotation.bodyLines, linkGenerator),
+          name: currentAnnotation.name,
+        })) ?? []
+    );
+  }
+
+  function extractAnnotationBody(type: Documentable, annotationName: string): string | undefined {
+    return type.docComment?.annotations.find(
+      (currentAnnotation) => currentAnnotation.name.toLowerCase() === annotationName,
+    )?.body;
+  }
+
+  function extractSeeAnnotations(type: Documentable): string[] {
+    return (
+      type.docComment?.annotations
+        .filter((currentAnnotation) => currentAnnotation.name.toLowerCase() === 'see')
+        .map((currentAnnotation) => currentAnnotation.body) ?? []
+    );
+  }
+
+  return {
+    ...adaptDescribable(documentable.docComment?.descriptionLines, linkGenerator),
+    annotations: documentable.annotations.map((annotation) => annotation.type.toUpperCase()),
+    customTags: extractCustomTags(documentable),
+    example: {
+      headingLevel: subHeadingLevel,
+      heading: 'Example',
+      value: describableToRenderableContent(documentable.docComment?.exampleAnnotation?.bodyLines, linkGenerator),
+    },
+    group: extractAnnotationBody(documentable, 'group'),
+    author: extractAnnotationBody(documentable, 'author'),
+    date: extractAnnotationBody(documentable, 'date'),
+    sees: extractSeeAnnotations(documentable).map(linkGenerator),
+  };
+}

package/src/core/markdown/adapters/fields-and-properties.ts

@@ -0,0 +1,45 @@
+import {
+  CodeBlock,
+  FieldMirrorWithInheritance,
+  PropertyMirrorWithInheritance,
+  RenderableField,
+  GetRenderableContentByTypeName,
+} from './types';
+import { adaptDocumentable } from './documentables';
+
+export function adaptFieldOrProperty(
+  field: FieldMirrorWithInheritance | PropertyMirrorWithInheritance,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableField {
+  function buildSignature(): CodeBlock {
+    const { access_modifier, name } = field;
+    const memberModifiers = field.memberModifiers.join(' ');
+    const codeContents = `${access_modifier} ${memberModifiers} ${name}`
+      // remove double spaces
+      .replace(/ {2}/g, ' ');
+    return {
+      __type: 'code-block',
+      language: 'apex',
+      content: [codeContents],
+    };
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(field, linkGenerator, baseHeadingLevel + 1),
+    heading: field.name,
+    type: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Type',
+      value: linkGenerator(field.typeReference.rawDeclaration),
+    },
+    inherited: field.inherited,
+    accessModifier: field.access_modifier,
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: buildSignature(),
+    },
+  };
+}

package/src/{adapters/references.ts → core/markdown/adapters/inline.ts}

@@ -1,13 +1,14 @@
-import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
-import { Link, RenderableContent, StringOrLink } from '../templating/types';
+import { InlineCode, Link, RenderableContent } from './types';
+import { pipe } from 'fp-ts/function';
+import { apply } from '#utils/fp';
 
-export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+type InlineRenderableContent = InlineCode | Link | string;
 
-export const linkFromTypeNameGenerator: GetRenderableContentByTypeName =
-  ClassFileGeneratorHelper.getRenderableLinkByTypeName;
+type ToInlineRenderableContent = (typeName: string) => InlineRenderableContent;
 
 function defaultGetEmailByReference(email: string): Link {
   return {
+    __type: 'link',
     title: email,
     url: `mailto:${email}`,
   };
@@ -15,22 +16,51 @@ function defaultGetEmailByReference(email: string): Link {
 
 export function replaceInlineReferences(
   text: string,
-  linkReplacer: GetRenderableContentByTypeName = linkFromTypeNameGenerator,
-  emailReplacer: GetRenderableContentByTypeName = defaultGetEmailByReference,
+  linkReplacer: ToInlineRenderableContent,
+  emailReplacer: ToInlineRenderableContent = defaultGetEmailByReference,
 ): RenderableContent[] {
-  return replaceInlineEmails(replaceInlineLinks([text], linkReplacer), emailReplacer);
+  const inlineLinks = apply(replaceInlineLinks, linkReplacer);
+  const inlineEmails = apply(replaceInlineEmails, emailReplacer);
+
+  return pipe(inlineCode([text]), inlineLinks, inlineEmails);
+}
+
+function inlineCode(renderableContents: RenderableContent[]): RenderableContent[] {
+  return renderableContents.flatMap((renderableContent) => inlineCodeContent(renderableContent));
+}
+
+// Replace string that is inline code with InlineCode
+// Inline code is any text that backticks surround
+function inlineCodeContent(renderableContent: RenderableContent): RenderableContent[] {
+  if (typeof renderableContent !== 'string') {
+    return [renderableContent];
+  }
+
+  function inlineCodeLink(text: string): InlineCode {
+    return {
+      __type: 'inline-code',
+      content: text,
+    };
+  }
+
+  const text = renderableContent;
+
+  // Matches any text surrounded by backticks
+  const codeFormatRegEx = '`([^`]*)`';
+  const matches = match(codeFormatRegEx, text);
+  return createRenderableContents(matches, text, inlineCodeLink);
 }
 
 function replaceInlineLinks(
+  getLinkByTypeName: ToInlineRenderableContent,
   renderableContents: RenderableContent[],
-  getLinkByTypeName: GetRenderableContentByTypeName,
 ): RenderableContent[] {
   return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
 }
 
 function inlineLinkContent(
   renderableContent: RenderableContent,
-  getLinkByTypeName: GetRenderableContentByTypeName,
+  getLinkByTypeName: ToInlineRenderableContent,
 ): RenderableContent[] {
   if (typeof renderableContent !== 'string') {
     return [renderableContent];
@@ -45,15 +75,15 @@ function inlineLinkContent(
 }
 
 export function replaceInlineEmails(
+  getLinkByTypeName: ToInlineRenderableContent,
   renderableContents: RenderableContent[],
-  getLinkByTypeName: GetRenderableContentByTypeName,
 ): RenderableContent[] {
   return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
 }
 
 function inlineEmailContent(
   renderableContent: RenderableContent,
-  getLinkByTypeName: GetRenderableContentByTypeName,
+  getLinkByTypeName: ToInlineRenderableContent,
 ): RenderableContent[] {
   if (typeof renderableContent !== 'string') {
     return [renderableContent];
@@ -82,7 +112,7 @@ function match(regex: string, text: string) {
   return matches;
 }
 
-function createRenderableContents(matches: RegExpExecArray[], text: string, linker: GetRenderableContentByTypeName) {
+function createRenderableContents(matches: RegExpExecArray[], text: string, linker: ToInlineRenderableContent) {
   if (matches.length === 0) {
     return [text];
   }

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

@@ -0,0 +1,133 @@
+import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
+import {
+  RenderableConstructor,
+  RenderableMethod,
+  MethodMirrorWithInheritance,
+  CodeBlock,
+  GetRenderableContentByTypeName,
+} from './types';
+import { adaptDescribable, adaptDocumentable } from './documentables';
+import { Documentable } from './types';
+
+export function adaptMethod(
+  method: MethodMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableMethod {
+  function buildTitle(method: MethodMirrorWithInheritance): string {
+    const { name, parameters } = method;
+    const parametersString = parameters.map((param) => param.name).join(', ');
+    return `${name}(${parametersString})`;
+  }
+
+  function buildSignature(method: MethodMirrorWithInheritance): CodeBlock {
+    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 {
+      __type: 'code-block',
+      language: 'apex',
+      content: [`${access_modifier} ${members}${typeReference.rawDeclaration} ${name}(${parameters})`],
+    };
+  }
+
+  return {
+    headingLevel: baseHeadingLevel,
+    doc: adaptDocumentable(method, linkGenerator, baseHeadingLevel + 1),
+    heading: buildTitle(method as MethodMirrorWithInheritance),
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: buildSignature(method as MethodMirrorWithInheritance),
+    },
+    returnType: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Return Type',
+      value: {
+        ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines, linkGenerator),
+        type: linkGenerator(method.typeReference.rawDeclaration),
+      },
+    },
+    throws: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Throws',
+      value: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown, linkGenerator)),
+    },
+    parameters: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Parameters',
+      value: method.parameters.map((param) => mapParameters(method, param, linkGenerator)),
+    },
+    inherited: (method as MethodMirrorWithInheritance).inherited,
+  };
+}
+
+export function adaptConstructor(
+  typeName: string,
+  constructor: ConstructorMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+  baseHeadingLevel: number,
+): RenderableConstructor {
+  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): CodeBlock {
+    const { access_modifier } = constructor;
+    const parameters = constructor.parameters
+      .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
+      .join(', ');
+    return {
+      __type: 'code-block',
+      language: 'apex',
+      content: [`${access_modifier} ${name}(${parameters})`],
+    };
+  }
+
+  return {
+    doc: adaptDocumentable(constructor, linkGenerator, baseHeadingLevel + 1),
+    headingLevel: baseHeadingLevel,
+    heading: buildTitle(typeName, constructor),
+    signature: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Signature',
+      value: buildSignature(typeName, constructor),
+    },
+    parameters: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Parameters',
+      value: constructor.parameters.map((param) => mapParameters(constructor, param, linkGenerator)),
+    },
+    throws: {
+      headingLevel: baseHeadingLevel + 1,
+      heading: 'Throws',
+      value: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown, linkGenerator)),
+    },
+  };
+}
+
+function mapParameters(
+  documentable: Documentable,
+  param: ParameterMirror,
+  linkGenerator: GetRenderableContentByTypeName,
+) {
+  const paramAnnotation = documentable.docComment?.paramAnnotations.find(
+    (pa) => pa.paramName.toLowerCase() === param.name.toLowerCase(),
+  );
+  return {
+    ...adaptDescribable(paramAnnotation?.bodyLines, linkGenerator),
+    name: param.name,
+    type: linkGenerator(param.typeReference.rawDeclaration),
+  };
+}
+
+function mapThrows(thrown: ThrowsAnnotation, linkGenerator: GetRenderableContentByTypeName) {
+  return {
+    ...adaptDescribable(thrown.bodyLines, linkGenerator),
+    type: linkGenerator(thrown.exceptionName),
+  };
+}

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

@@ -0,0 +1,35 @@
+import { MarkdownGeneratorConfig } from '../generate-docs';
+import { DocPageReference, ParsedFile } from '../../shared/types';
+import { Type } from '@cparra/apex-reflection';
+
+export function parsedFilesToReferenceGuide(
+  config: MarkdownGeneratorConfig,
+  parsedFiles: ParsedFile[],
+): Record<string, DocPageReference> {
+  return parsedFiles.reduce<Record<string, DocPageReference>>((acc, parsedFile) => {
+    acc[parsedFile.type.name] = parsedFileToDocPageReference(config, parsedFile);
+    return acc;
+  }, {});
+}
+
+function parsedFileToDocPageReference(config: MarkdownGeneratorConfig, parsedFile: ParsedFile): DocPageReference {
+  return {
+    source: parsedFile.source,
+    displayName: parsedFile.type.name,
+    pathFromRoot: `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`,
+  };
+}
+
+function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
+  const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
+  return groupAnnotation?.body ?? config.defaultGroupName;
+}
+
+function slugify(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '') // Remove non-alphanumeric characters except spaces and hyphens
+    .trim()
+    .replace(/\s+/g, '-') // Replace spaces with hyphens
+    .replace(/-+/g, '-'); // Replace multiple hyphens with a single hyphen
+}

package/src/core/markdown/adapters/renderable-bundle.ts

@@ -0,0 +1,78 @@
+import { DocPageReference, ParsedFile } from '../../shared/types';
+import { Link, ReferenceGuideReference, Renderable, RenderableBundle, StringOrLink } from './types';
+import { typeToRenderable } from './apex-types';
+import { adaptDescribable } from './documentables';
+import { MarkdownGeneratorConfig } from '../generate-docs';
+import { apply } from '#utils/fp';
+import { Type } from '@cparra/apex-reflection';
+import * as path from 'path';
+
+export function parsedFilesToRenderableBundle(
+  config: MarkdownGeneratorConfig,
+  parsedFiles: ParsedFile[],
+  references: Record<string, DocPageReference>,
+): RenderableBundle {
+  const referenceFinder = apply(linkGenerator, references, config.documentationRootDir);
+
+  function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
+    return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
+      addToReferenceGuide(referenceFinder, config, references),
+      {},
+    );
+  }
+
+  function toRenderables(parsedFiles: ParsedFile[]): Renderable[] {
+    return parsedFiles.reduce<Renderable[]>((acc, parsedFile) => {
+      const renderable = typeToRenderable(parsedFile, referenceFinder, config);
+      acc.push(renderable);
+      return acc;
+    }, []);
+  }
+
+  return {
+    referencesByGroup: toReferenceGuide(parsedFiles),
+    renderables: toRenderables(parsedFiles),
+  };
+}
+
+function addToReferenceGuide(
+  findLinkFromHome: (referenceName: string) => string | Link,
+  config: MarkdownGeneratorConfig,
+  references: Record<string, DocPageReference>,
+) {
+  return (acc: Record<string, ReferenceGuideReference[]>, parsedFile: ParsedFile) => {
+    const group: string = getTypeGroup(parsedFile.type, config);
+    if (!acc[group]) {
+      acc[group] = [];
+    }
+    acc[group].push({
+      reference: references[parsedFile.type.name],
+      title: findLinkFromHome(parsedFile.type.name) as Link,
+      description: adaptDescribable(parsedFile.type.docComment?.descriptionLines, findLinkFromHome).description ?? null,
+    });
+
+    return acc;
+  };
+}
+
+const linkGenerator = (
+  references: Record<string, DocPageReference>,
+  documentationRootDir: string,
+  referenceName: string,
+): StringOrLink => {
+  const reference: DocPageReference | undefined = references[referenceName];
+
+  return reference
+    ? // Starting the path with a "/" will ensure the link will always be relative to the root of the site.
+      {
+        __type: 'link',
+        title: reference.displayName,
+        url: path.join('/', documentationRootDir, reference.pathFromRoot),
+      }
+    : referenceName;
+};
+
+function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
+  const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
+  return groupAnnotation?.body ?? config.defaultGroupName;
+}

package/src/core/markdown/adapters/renderable-to-page-data.ts

@@ -0,0 +1,89 @@
+import { ReferenceGuideReference, Renderable, RenderableBundle, RenderableEnum } from './types';
+import { DocPageData, DocumentationBundle } from '../../shared/types';
+import { pipe } from 'fp-ts/function';
+import { CompilationRequest, Template } from '../templates/template';
+import { enumMarkdownTemplate } from '../templates/enum-template';
+import { interfaceMarkdownTemplate } from '../templates/interface-template';
+import { classMarkdownTemplate } from '../templates/class-template';
+import { defaults } from '../../../defaults';
+
+export const convertToDocumentationBundle = (
+  referenceGuideTemplate: string,
+  { referencesByGroup, renderables }: RenderableBundle,
+): DocumentationBundle => ({
+  referenceGuide: {
+    frontmatter: null,
+    content: referencesToReferenceGuideContent(referencesByGroup, referenceGuideTemplate),
+    filePath: 'index.md',
+  },
+  docs: renderables.map((renderable: Renderable) =>
+    renderableToPageData(Object.values(referencesByGroup).flat(), renderable),
+  ),
+});
+
+function referencesToReferenceGuideContent(
+  references: { [key: string]: ReferenceGuideReference[] },
+  template: string,
+): string {
+  function alphabetizeReferences(references: { [key: string]: ReferenceGuideReference[] }): {
+    [key: string]: ReferenceGuideReference[];
+  } {
+    return Object.keys(references)
+      .sort((a, b) => a.localeCompare(b))
+      .reduce<{ [key: string]: ReferenceGuideReference[] }>((acc, key) => {
+        acc[key] = references[key].sort((a, b) => a.title.toString().localeCompare(b.title.toString()));
+        return acc;
+      }, {});
+  }
+
+  return pipe(references, alphabetizeReferences, (references) =>
+    compile({
+      template: template,
+      source: references,
+    }),
+  );
+}
+
+function renderableToPageData(referenceGuideReference: ReferenceGuideReference[], renderable: Renderable): DocPageData {
+  function buildDocOutput(renderable: Renderable, docContents: string): DocPageData {
+    const reference: ReferenceGuideReference = referenceGuideReference.find(
+      (ref) => ref.reference.source.name.toLowerCase() === renderable.name.toLowerCase(),
+    )!;
+
+    return {
+      source: {
+        filePath: renderable.filePath,
+        name: renderable.name,
+        type: renderable.type,
+      },
+      filePath: reference!.reference.pathFromRoot,
+      frontmatter: null,
+      content: docContents,
+      group: renderable.doc.group ?? defaults.defaultGroupName,
+    };
+  }
+
+  return pipe(renderable, resolveApexTypeTemplate, compile, (docContents) => buildDocOutput(renderable, docContents));
+}
+
+function resolveApexTypeTemplate(renderable: Renderable): CompilationRequest {
+  function getTemplate(renderable: Renderable): string {
+    switch (renderable.type) {
+      case 'enum':
+        return enumMarkdownTemplate;
+      case 'interface':
+        return interfaceMarkdownTemplate;
+      case 'class':
+        return classMarkdownTemplate;
+    }
+  }
+
+  return {
+    template: getTemplate(renderable),
+    source: renderable as RenderableEnum,
+  };
+}
+
+function compile(request: CompilationRequest): string {
+  return Template.getInstance().compile(request);
+}

package/src/core/markdown/adapters/type-utils.ts

@@ -0,0 +1,13 @@
+import { CodeBlock, EmptyLine, InlineCode, RenderableContent } from './types';
+
+export function isEmptyLine(content: RenderableContent): content is EmptyLine {
+  return Object.keys(content).includes('__type') && (content as { __type: string }).__type === 'empty-line';
+}
+
+export function isCodeBlock(content: RenderableContent): content is CodeBlock {
+  return Object.keys(content).includes('__type') && (content as { __type: string }).__type === 'code-block';
+}
+
+export function isInlineCode(content: RenderableContent): content is InlineCode {
+  return Object.keys(content).includes('__type') && (content as { __type: string }).__type === 'inline-code';
+}