@cparra/apexdocs 2.25.0-alpha.8 → 2.25.0

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

@@ -1,116 +0,0 @@
-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

@@ -1,45 +0,0 @@
-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/core/markdown/adapters/inline.ts

@@ -1,143 +0,0 @@
-import { InlineCode, Link, RenderableContent } from './types';
-import { pipe } from 'fp-ts/function';
-import { apply } from '#utils/fp';
-
-type InlineRenderableContent = InlineCode | Link | string;
-
-type ToInlineRenderableContent = (typeName: string) => InlineRenderableContent;
-
-function defaultGetEmailByReference(email: string): Link {
-  return {
-    __type: 'link',
-    title: email,
-    url: `mailto:${email}`,
-  };
-}
-
-export function replaceInlineReferences(
-  text: string,
-  linkReplacer: ToInlineRenderableContent,
-  emailReplacer: ToInlineRenderableContent = defaultGetEmailByReference,
-): RenderableContent[] {
-  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[],
-): RenderableContent[] {
-  return renderableContents.flatMap((renderableContent) => inlineLinkContent(renderableContent, getLinkByTypeName));
-}
-
-function inlineLinkContent(
-  renderableContent: RenderableContent,
-  getLinkByTypeName: ToInlineRenderableContent,
-): RenderableContent[] {
-  if (typeof renderableContent !== 'string') {
-    return [renderableContent];
-  }
-
-  const text = renderableContent;
-
-  // Matches either `<<ClassName>>` or `{@link ClassName}`
-  const linkFormatRegEx = '{@link (.*?)}|<<([^>]+)>>';
-  const matches = match(linkFormatRegEx, text);
-  return createRenderableContents(matches, text, getLinkByTypeName);
-}
-
-export function replaceInlineEmails(
-  getLinkByTypeName: ToInlineRenderableContent,
-  renderableContents: RenderableContent[],
-): RenderableContent[] {
-  return renderableContents.flatMap((renderableContent) => inlineEmailContent(renderableContent, getLinkByTypeName));
-}
-
-function inlineEmailContent(
-  renderableContent: RenderableContent,
-  getLinkByTypeName: ToInlineRenderableContent,
-): RenderableContent[] {
-  if (typeof renderableContent !== 'string') {
-    return [renderableContent];
-  }
-
-  const text = renderableContent;
-
-  // Parsing references using the format '{@email email}'
-  const linkFormatRegEx = '{@email (.*?)}';
-  const matches = match(linkFormatRegEx, text);
-  return createRenderableContents(matches, text, getLinkByTypeName);
-}
-
-function match(regex: string, text: string) {
-  const expression = new RegExp(regex, 'gi');
-  let match;
-  const matches = [];
-
-  do {
-    match = expression.exec(text);
-    if (match) {
-      matches.push(match);
-    }
-  } while (match);
-
-  return matches;
-}
-
-function createRenderableContents(matches: RegExpExecArray[], text: string, linker: ToInlineRenderableContent) {
-  if (matches.length === 0) {
-    return [text];
-  }
-
-  const result: RenderableContent[] = [];
-  let lastIndex = 0;
-  for (const match of matches) {
-    const index = match.index;
-    const length = match[0].length;
-
-    // loop through the matches (skip the first one, which is the full match)
-    // until we find the first capturing group that has a value
-    const capturedGroup = match.slice(1).find((group) => group);
-    if (!capturedGroup) {
-      continue;
-    }
-    result.push(text.slice(lastIndex, index));
-    result.push(linker(capturedGroup));
-
-    lastIndex = index + length;
-  }
-
-  if (lastIndex < text.length) {
-    result.push(text.slice(lastIndex));
-  }
-
-  return result;
-}

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

@@ -1,133 +0,0 @@
-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/renderable-bundle.ts

@@ -1,144 +0,0 @@
-import { ParsedFile } from '../../shared/types';
-import { Link, RenderableBundle, StringOrLink } from './types';
-import { typeToRenderable } from './apex-types';
-import { adaptDescribable } from './documentables';
-import { Type } from '@cparra/apex-reflection';
-import { MarkdownGeneratorConfig } from '../generate-docs';
-
-export function parsedFilesToRenderableBundle(
-  config: MarkdownGeneratorConfig,
-  parsedFiles: ParsedFile[],
-): RenderableBundle {
-  return parsedFiles.reduce<RenderableBundle>(
-    (acc, parsedFile) => {
-      const renderable = typeToRenderable(
-        parsedFile,
-        (referenceName) => {
-          return linkFromTypeNameGenerator(
-            parsedFile.type,
-            parsedFiles.map((file) => file.type),
-            referenceName,
-            config,
-          );
-        },
-        config,
-      );
-      acc.renderables.push(renderable);
-
-      const descriptionLines = parsedFile.type.docComment?.descriptionLines;
-      const reference = {
-        typeName: parsedFile.type.name,
-        directory: getDirectoryFromRoot(config, parsedFile.type),
-        title: getLinkFromRoot(config, parsedFile.type),
-        description: adaptDescribable(descriptionLines, (referenceName) =>
-          getPossibleLinkFromRoot(
-            config,
-            referenceName,
-            findType(
-              parsedFiles.map((file) => file.type),
-              referenceName,
-            ),
-          ),
-        ).description,
-      };
-
-      const group = getTypeGroup(parsedFile.type, config);
-      if (!acc.references[group]) {
-        acc.references[group] = [];
-      }
-      acc.references[group].push(reference);
-
-      return acc;
-    },
-    {
-      references: {},
-      renderables: [],
-    },
-  );
-}
-
-function linkFromTypeNameGenerator(
-  typeBeingDocumented: Type,
-  repository: Type[],
-  referenceName: string,
-  config: MarkdownGeneratorConfig,
-): StringOrLink {
-  const type = findType(repository, referenceName);
-  if (!type) {
-    // If the type is not found, we return the type name as a string.
-    return referenceName;
-  }
-
-  const [fullClassName, fileLink] = getFileLinkTuple(typeBeingDocumented, type, config);
-  return {
-    __type: 'link',
-    title: fullClassName,
-    url: fileLink,
-  };
-}
-
-function getPossibleLinkFromRoot(config: MarkdownGeneratorConfig, fallback: string, type?: Type): StringOrLink {
-  if (!type) {
-    return fallback;
-  }
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
-  const title = `${namespacePrefix}${type.name}`;
-  return {
-    __type: 'link',
-    title: title,
-    url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
-  };
-}
-
-function getDirectoryFromRoot(config: MarkdownGeneratorConfig, type?: Type): string {
-  if (!type) {
-    return '';
-  }
-  return `./${getSanitizedGroup(type, config)}`;
-}
-
-function findType(repository: Type[], referenceName: string) {
-  return repository.find((currentType: Type) => currentType.name.toLowerCase() === referenceName.toLowerCase());
-}
-
-function getFileLinkTuple(
-  typeBeingDocumented: Type,
-  referencedType: Type,
-  config: MarkdownGeneratorConfig,
-): [string, string] {
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
-  const directoryRoot = `${getDirectoryRoot(typeBeingDocumented, referencedType, config)}`;
-  // TODO: Instead of adding a "." to the name when there is a namespace, maybe we want to create a folder for everything
-  // within that namespace and put the files in there.
-  const fullClassName = `${namespacePrefix}${referencedType.name}`;
-  return [fullClassName, `${directoryRoot}${fullClassName}.md`];
-}
-
-function getDirectoryRoot(typeBeingDocumented: Type, referencedType: Type, config: MarkdownGeneratorConfig) {
-  if (getTypeGroup(typeBeingDocumented, config) === getTypeGroup(referencedType, config)) {
-    // If the types the same groups then we simply link directly to that file
-    return './';
-  } else {
-    // If the types have different groups, then we have to go up a directory
-    return `../${getSanitizedGroup(referencedType, config)}/`;
-  }
-}
-
-function getTypeGroup(type: Type, config: MarkdownGeneratorConfig): string {
-  const groupAnnotation = type.docComment?.annotations.find((annotation) => annotation.name.toLowerCase() === 'group');
-  return groupAnnotation?.body ?? config.defaultGroupName;
-}
-
-function getSanitizedGroup(classModel: Type, config: MarkdownGeneratorConfig) {
-  return getTypeGroup(classModel, config).replace(/ /g, '-').replace('.', '');
-}
-
-function getLinkFromRoot(config: MarkdownGeneratorConfig, type: Type): Link {
-  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
-  const title = `${namespacePrefix}${type.name}`;
-  return {
-    __type: 'link',
-    title: title,
-    url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
-  };
-}

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

@@ -1,92 +0,0 @@
-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';
-
-export const convertToDocumentationBundle = (
-  referenceGuideTemplate: string,
-  { references, renderables }: RenderableBundle,
-): DocumentationBundle => ({
-  referenceGuide: {
-    directory: '',
-    frontmatter: null,
-    content: referencesToReferenceGuideContent(references, referenceGuideTemplate),
-    fileExtension: 'md',
-    fileName: 'index',
-  },
-  docs: renderables.map((renderable: Renderable) => renderableToPageData(Object.values(references).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.find(
-      (ref) => ref.typeName.toLowerCase() === renderable.name.toLowerCase(),
-    );
-
-    const namespacePrefix = renderable.namespace ? `${renderable.namespace}.` : '';
-
-    return {
-      source: {
-        filePath: renderable.filePath,
-        name: renderable.name,
-        type: renderable.type,
-      },
-      fileName: `${namespacePrefix}${renderable.name}`,
-      fileExtension: 'md',
-      directory: `${reference?.directory}`,
-      frontmatter: null,
-      content: docContents,
-      group: renderable.doc.group ?? 'Miscellaneous',
-    };
-  }
-
-  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

@@ -1,13 +0,0 @@
-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';
-}