@cparra/apexdocs 2.25.0 → 3.0.0-alpha.10

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,37 @@
+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 {
+  const path = `${slugify(getTypeGroup(parsedFile.type, config))}/${parsedFile.type.name}.md`;
+  return {
+    source: parsedFile.source,
+    displayName: parsedFile.type.name,
+    outputDocPath: path,
+    referencePath: path,
+  };
+}
+
+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,61 @@
+import { DocPageReference, ParsedFile } from '../../shared/types';
+import { Link, ReferenceGuideReference, Renderable, RenderableBundle } 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 { generateLink } from './generate-link';
+
+export function parsedFilesToRenderableBundle(
+  config: MarkdownGeneratorConfig,
+  parsedFiles: ParsedFile[],
+  references: Record<string, DocPageReference>,
+): RenderableBundle {
+  const referenceFinder = apply(generateLink(config.linkingStrategy), references);
+
+  function toReferenceGuide(parsedFiles: ParsedFile[]): Record<string, ReferenceGuideReference[]> {
+    return parsedFiles.reduce<Record<string, ReferenceGuideReference[]>>(
+      addToReferenceGuide(apply(referenceFinder, '__base__'), config, references),
+      {},
+    );
+  }
+
+  function toRenderables(parsedFiles: ParsedFile[]): Renderable[] {
+    return parsedFiles.reduce<Renderable[]>((acc, parsedFile) => {
+      const renderable = typeToRenderable(parsedFile, apply(referenceFinder, parsedFile.source.name), 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;
+  };
+}
+
+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),
+    outputDocPath: '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,
+      },
+      outputDocPath: reference!.reference.outputDocPath,
+      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';
+}

package/src/core/markdown/adapters/types.d.ts

@@ -0,0 +1,180 @@
+// Apex Reflection-based types
+import {
+  Annotation as MirrorAnnotation,
+  ClassMirror,
+  DocComment,
+  FieldMirror,
+  MethodMirror,
+  PropertyMirror,
+} from '@cparra/apex-reflection';
+import { DocPageReference } from '../../shared/types';
+
+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;
+
+// Renderable types
+
+export type ReferenceGuideReference = {
+  reference: DocPageReference;
+  title: Link;
+  description: RenderableContent[] | null;
+};
+
+export type RenderableBundle = {
+  // References are grouped by their defined @group annotation
+  referencesByGroup: Record<string, ReferenceGuideReference[]>;
+  renderables: Renderable[];
+};
+
+export type Link = {
+  readonly __type: 'link';
+  title: string;
+  url: string;
+};
+
+export type EmptyLine = {
+  __type: 'empty-line';
+};
+
+export type StringOrLink = string | Link;
+
+export type GetRenderableContentByTypeName = (typeName: string) => StringOrLink;
+
+export type RenderableContent = StringOrLink | EmptyLine | CodeBlock | InlineCode;
+
+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 = {
+  readonly __type: 'code-block';
+  language: string;
+  content: string[];
+};
+
+type InlineCode = {
+  readonly __type: 'inline-code';
+  content: string;
+};
+
+type RenderableDocumentation = {
+  annotations?: Annotation[];
+  description?: RenderableContent[];
+  customTags?: CustomTag[];
+  example: RenderableSection<RenderableContent[] | 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) & { filePath: string };