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

package/src/core/adapters/documentables.ts

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

package/src/{adapters → core/adapters}/fields-and-properties.ts

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

package/src/{adapters → core/adapters}/methods-and-constructors.ts

@@ -1,8 +1,7 @@
 import { ConstructorMirror, MethodMirror, ParameterMirror, ThrowsAnnotation } from '@cparra/apex-reflection';
-import { RenderableConstructor, RenderableMethod } from '../core/renderable/types';
-import { MethodMirrorWithInheritance } from '../model/inheritance';
+import { RenderableConstructor, RenderableMethod, MethodMirrorWithInheritance, CodeBlock } from './types';
 import { adaptDescribable, adaptDocumentable } from './documentables';
-import { GetRenderableContentByTypeName, linkFromTypeNameGenerator } from './references';
+import { GetRenderableContentByTypeName } from './references';
 import { Documentable } from './types';
 
 export function adaptMethod(
@@ -16,13 +15,17 @@ export function adaptMethod(
     return `${name}(${parametersString})`;
   }
 
-  function buildSignature(method: MethodMirrorWithInheritance): string {
+  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 `${access_modifier} ${members}${typeReference.rawDeclaration} ${name}(${parameters})`;
+    return {
+      __type: 'code-block',
+      language: 'apex',
+      content: [`${access_modifier} ${members}${typeReference.rawDeclaration} ${name}(${parameters})`],
+    };
   }
 
   return {
@@ -32,25 +35,25 @@ export function adaptMethod(
     signature: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Signature',
-      value: [buildSignature(method as MethodMirrorWithInheritance)],
+      value: buildSignature(method as MethodMirrorWithInheritance),
     },
     returnType: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Return Type',
       value: {
         ...adaptDescribable(method.docComment?.returnAnnotation?.bodyLines, linkGenerator),
-        type: linkFromTypeNameGenerator(method.typeReference.rawDeclaration),
+        type: linkGenerator(method.typeReference.rawDeclaration),
       },
     },
     throws: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Throws',
-      value: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+      value: method.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown, linkGenerator)),
     },
     parameters: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Parameters',
-      value: method.parameters.map((param) => mapParameters(method, param)),
+      value: method.parameters.map((param) => mapParameters(method, param, linkGenerator)),
     },
     inherited: (method as MethodMirrorWithInheritance).inherited,
   };
@@ -68,12 +71,16 @@ export function adaptConstructor(
     return `${name}(${parametersString})`;
   }
 
-  function buildSignature(name: string, constructor: ConstructorMirror): string {
+  function buildSignature(name: string, constructor: ConstructorMirror): CodeBlock {
     const { access_modifier } = constructor;
     const parameters = constructor.parameters
       .map((param) => `${param.typeReference.rawDeclaration} ${param.name}`)
       .join(', ');
-    return `${access_modifier} ${name}(${parameters})`;
+    return {
+      __type: 'code-block',
+      language: 'apex',
+      content: [`${access_modifier} ${name}(${parameters})`],
+    };
   }
 
   return {
@@ -83,35 +90,39 @@ export function adaptConstructor(
     signature: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Signature',
-      value: [buildSignature(typeName, constructor)],
+      value: buildSignature(typeName, constructor),
     },
     parameters: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Parameters',
-      value: constructor.parameters.map((param) => mapParameters(constructor, param)),
+      value: constructor.parameters.map((param) => mapParameters(constructor, param, linkGenerator)),
     },
     throws: {
       headingLevel: baseHeadingLevel + 1,
       heading: 'Throws',
-      value: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown)),
+      value: constructor.docComment?.throwsAnnotations.map((thrown) => mapThrows(thrown, linkGenerator)),
     },
   };
 }
 
-function mapParameters(documentable: Documentable, param: ParameterMirror) {
+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, linkFromTypeNameGenerator),
+    ...adaptDescribable(paramAnnotation?.bodyLines, linkGenerator),
     name: param.name,
-    type: linkFromTypeNameGenerator(param.typeReference.rawDeclaration),
+    type: linkGenerator(param.typeReference.rawDeclaration),
   };
 }
 
-function mapThrows(thrown: ThrowsAnnotation) {
+function mapThrows(thrown: ThrowsAnnotation, linkGenerator: GetRenderableContentByTypeName) {
   return {
-    ...adaptDescribable(thrown.bodyLines, linkFromTypeNameGenerator),
-    type: linkFromTypeNameGenerator(thrown.exceptionName),
+    ...adaptDescribable(thrown.bodyLines, linkGenerator),
+    type: linkGenerator(thrown.exceptionName),
   };
 }

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

@@ -1,13 +1,10 @@
-import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
-import { Link, RenderableContent, StringOrLink } from '../core/renderable/types';
+import { Link, RenderableContent, StringOrLink } from './types';
 
 export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
 
-export const linkFromTypeNameGenerator: GetRenderableContentByTypeName =
-  ClassFileGeneratorHelper.getRenderableLinkByTypeName;
-
 function defaultGetEmailByReference(email: string): Link {
   return {
+    __type: 'link',
     title: email,
     url: `mailto:${email}`,
   };
@@ -15,7 +12,7 @@ function defaultGetEmailByReference(email: string): Link {
 
 export function replaceInlineReferences(
   text: string,
-  linkReplacer: GetRenderableContentByTypeName = linkFromTypeNameGenerator,
+  linkReplacer: GetRenderableContentByTypeName,
   emailReplacer: GetRenderableContentByTypeName = defaultGetEmailByReference,
 ): RenderableContent[] {
   return replaceInlineEmails(replaceInlineLinks([text], linkReplacer), emailReplacer);

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

@@ -0,0 +1,9 @@
+import { CodeBlock, EmptyLine, 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';
+}

package/src/core/{renderable → adapters}/types.d.ts

@@ -1,15 +1,42 @@
+// Apex Reflection-based types
+import {
+  Annotation as MirrorAnnotation,
+  ClassMirror,
+  DocComment,
+  FieldMirror,
+  MethodMirror,
+  PropertyMirror,
+} from '@cparra/apex-reflection';
+
+export type Describable = string[] | undefined;
+
+export type Documentable = {
+  annotations: MirrorAnnotation[];
+  docComment?: DocComment;
+};
+
+export type InheritanceSupport = { inherited: boolean };
+export type ClassMirrorWithInheritanceChain = ClassMirror & { inheritanceChain: string[] };
+export type FieldMirrorWithInheritance = FieldMirror & InheritanceSupport;
+export type PropertyMirrorWithInheritance = PropertyMirror & InheritanceSupport;
+export type MethodMirrorWithInheritance = MethodMirror & InheritanceSupport;
+export type FieldOrProperty = FieldMirrorWithInheritance | PropertyMirrorWithInheritance;
+
+// Renderable types
+
 export type Link = {
+  readonly __type: 'link';
   title: string;
   url: string;
 };
 
 export type EmptyLine = {
-  type: 'empty-line';
+  __type: 'empty-line';
 };
 
 export type StringOrLink = string | Link;
 
-export type RenderableContent = StringOrLink | EmptyLine;
+export type RenderableContent = StringOrLink | EmptyLine | CodeBlock;
 
 type EnumValue = {
   value: string;
@@ -22,11 +49,15 @@ type CustomTag = {
 };
 
 /**
- * Represents an annotation to a top-level type. For example @NamespaceAccessible.
+ * Represents an annotation to a top-level type. For example, @NamespaceAccessible.
  */
 type Annotation = string;
 
-type CodeBlock = string[];
+type CodeBlock = {
+  readonly __type: 'code-block';
+  language: string;
+  content: string[];
+};
 
 type RenderableDocumentation = {
   annotations?: Annotation[];
@@ -102,7 +133,7 @@ export type GroupedMember<T> = RenderableSection<T[]> & { groupDescription: stri
 
 export type RenderableClass = RenderableType & {
   type: 'class';
-  extends?: StringOrLink;
+  extends?: StringOrLink[];
   implements?: StringOrLink[];
   classModifier?: string;
   sharingModifier?: string;