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

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[];

package/src/core/generate-docs.ts

@@ -1,18 +1,22 @@
 import { ClassMirror, InterfaceMirror, reflect as mirrorReflection, Type } from '@cparra/apex-reflection';
-import { typeToRenderableType } from '../adapters/apex-types';
-import { Link, Renderable, RenderableContent, RenderableEnum, StringOrLink } from './renderable/types';
-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 * as O from 'fp-ts/Option';
+import { pipe } from 'fp-ts/function';
 import * as E from 'fp-ts/Either';
-import { flow, pipe } from 'fp-ts/function';
+
+import { typeToRenderable } from './adapters/apex-types';
+import { Link, Renderable, RenderableContent, RenderableEnum, StringOrLink } from './adapters/types';
 import { CompilationRequest, Template } from './template';
-import Manifest from '../model/manifest';
 import { referenceGuideTemplate } from './templates/reference-guide';
-import { adaptDescribable } from '../adapters/documentables';
+import { adaptDescribable } from './adapters/documentables';
 import { createInheritanceChain } from './inheritance-chain';
+import ApexBundle from './apex-bundle';
+import Manifest from './manifest';
 
-export const documentType = flow(typeToRenderableType, resolveApexTypeTemplate, compile);
+// TODO: The core should never depend on things from the outside, so it should never reference "back" (../)
+import { classMarkdownTemplate } from '../transpiler/markdown/plain-markdown/class-template';
+import { interfaceMarkdownTemplate } from '../transpiler/markdown/plain-markdown/interface-template';
+import { enumMarkdownTemplate } from '../transpiler/markdown/plain-markdown/enum-template';
+import MetadataProcessor from '../service/metadata-processor';
 
 export type DocumentationBundle = {
   format: 'markdown';
@@ -44,13 +48,13 @@ const configDefaults: DocumentationConfig = {
 };
 
 export function generateDocs(
-  input: string[],
+  input: ApexBundle[],
   config?: Partial<DocumentationConfig>,
-): E.Either<string[], DocumentationBundle> {
+): E.Either<ReflectionError[], DocumentationBundle> {
   const configWithDefaults = { ...configDefaults, ...config };
   return pipe(
     input,
-    (input) => input.map(reflectSourceBody),
+    (input) => input.map((bundle) => reflectSourceBody(bundle)),
     checkForReflectionErrors,
     E.map((types) => filterTypesOutOfScope(types, configWithDefaults.scope)),
     E.map((types) => types.map((type) => addInheritedMembers(type, types))),
@@ -82,7 +86,7 @@ type RenderableBundle = {
 function typesToRenderableBundle(types: Type[], config: DocumentationConfig) {
   return types.reduce<RenderableBundle>(
     (acc, type) => {
-      const renderable = typeToRenderableType(
+      const renderable = typeToRenderable(
         type,
         (referenceName) => {
           return linkFromTypeNameGenerator(type, types, referenceName, config);
@@ -159,12 +163,12 @@ function filterTypesOutOfScope(types: Type[], scope: string[]): Type[] {
   return new Manifest(types).filteredByAccessModifierAndAnnotations(scope);
 }
 
-function checkForReflectionErrors(reflectionResult: E.Either<string, Type>[]) {
-  function reduceReflectionResultIntoSingleEither(results: E.Either<string, Type>[]): {
-    errors: string[];
+function checkForReflectionErrors(reflectionResult: E.Either<ReflectionError, Type>[]) {
+  function reduceReflectionResultIntoSingleEither(results: E.Either<ReflectionError, Type>[]): {
+    errors: ReflectionError[];
     types: Type[];
   } {
-    return results.reduce<{ errors: string[]; types: Type[] }>(
+    return results.reduce<{ errors: ReflectionError[]; types: Type[] }>(
       (acc, result) => {
         E.isLeft(result) ? acc.errors.push(result.left) : acc.types.push(result.right);
         return acc;
@@ -181,10 +185,39 @@ function checkForReflectionErrors(reflectionResult: E.Either<string, Type>[]) {
   );
 }
 
-function reflectSourceBody(input: string): E.Either<string, Type> {
+function addFileMetadataToTypeAnnotation(type: Type, metadata: string | null): Type {
+  return pipe(
+    O.fromNullable(metadata),
+    O.map((metadata) => {
+      const metadataParams = MetadataProcessor.process(metadata);
+      metadataParams.forEach((value, key) => {
+        const declaration = `${key}: ${value}`;
+        type.annotations.push({
+          rawDeclaration: declaration,
+          name: declaration,
+          type: declaration,
+        });
+      });
+      return type;
+    }),
+    O.getOrElse(() => type),
+  );
+}
+
+export class ReflectionError {
+  constructor(
+    public file: string,
+    public message: string,
+  ) {}
+}
+
+function reflectSourceBody(apexBundle: ApexBundle): E.Either<ReflectionError, Type> {
+  const { filePath, rawTypeContent: input, rawMetadataContent: metadata } = apexBundle;
   const result = mirrorReflection(input);
   // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-  return result.error ? E.left(result.error.message) : E.right(result.typeMirror!);
+  return result.error
+    ? E.left(new ReflectionError(filePath, result.error.message))
+    : E.right(addFileMetadataToTypeAnnotation(result.typeMirror!, metadata));
 }
 
 function resolveApexTypeTemplate(renderable: Renderable): CompilationRequest {
@@ -330,6 +363,7 @@ function linkFromTypeNameGenerator(
 
   const [fullClassName, fileLink] = getFileLinkTuple(typeBeingDocumented, type, config);
   return {
+    __type: 'link',
     title: fullClassName,
     url: fileLink,
   };
@@ -362,6 +396,7 @@ function getPossibleLinkFromRoot(config: DocumentationConfig, fallback: string,
   const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
   const title = `${namespacePrefix}${type.name}`;
   return {
+    __type: 'link',
     title: title,
     url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
   };
@@ -371,6 +406,7 @@ function getLinkFromRoot(config: DocumentationConfig, 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/template.ts

@@ -7,8 +7,8 @@ import { fieldsPartialTemplate } from '../transpiler/markdown/plain-markdown/fie
 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 { CodeBlock, RenderableContent, StringOrLink } from './adapters/types';
+import { isCodeBlock, isEmptyLine } from './adapters/type-utils';
 import { groupedMembersPartialTemplate } from '../transpiler/markdown/plain-markdown/grouped-members-partial-template';
 
 export type CompilationRequest = {
@@ -32,7 +32,7 @@ export class Template {
 
     Handlebars.registerHelper('link', link);
     Handlebars.registerHelper('code', convertCodeBlock);
-    Handlebars.registerHelper('withLinks', resolveLinksInContent);
+    Handlebars.registerHelper('renderContent', resolveRenderableContent);
     Handlebars.registerHelper('heading', heading);
     Handlebars.registerHelper('inlineCode', inlineCode);
     Handlebars.registerHelper('splitAndCapitalize', splitAndCapitalize);
@@ -73,17 +73,17 @@ const inlineCode = (text: string) => {
   return new Handlebars.SafeString(`\`${text}\``);
 };
 
-const convertCodeBlock = (language: string, lines: string[]): Handlebars.SafeString => {
+const convertCodeBlock = (codeBlock: CodeBlock): Handlebars.SafeString => {
   return new Handlebars.SafeString(
     `
-\`\`\`${language}
-${lines.join('\n')}
+\`\`\`${codeBlock.language}
+${codeBlock.content.join('\n')}
 \`\`\`
   `.trim(),
   );
 };
 
-const resolveLinksInContent = (description?: RenderableContent[]): string => {
+const resolveRenderableContent = (description?: RenderableContent[]): string => {
   if (!description) {
     return '';
   }
@@ -92,8 +92,11 @@ const resolveLinksInContent = (description?: RenderableContent[]): string => {
     if (isEmptyLine(curr)) {
       return acc + '\n\n';
     }
-
-    return acc + link(curr).trim() + ' ';
+    if (isCodeBlock(curr)) {
+      return acc + convertCodeBlock(curr) + '\n';
+    } else {
+      return acc + Handlebars.escapeExpression(link(curr)).trim() + ' ';
+    }
   }
 
   return description.reduce(reduceDescription, '').trim();

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

@@ -7,7 +7,7 @@ export const referenceGuideTemplate = `
 {{#each this}}
 ### {{link title}}
 
-{{withLinks description}}
+{{{renderContent description}}}
 
 {{/each}}
 {{/each}}

package/src/model/__tests__/manifest.spec.ts

@@ -1,4 +1,4 @@
-import Manifest from '../manifest';
+import Manifest from '../../core/manifest';
 import { EnumMirror } from '@cparra/apex-reflection';
 
 const sampleEnum: EnumMirror = {

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

@@ -1,5 +1,5 @@
 import { MarkdownFile } from '../markdown-file';
-import { FieldMirrorWithInheritance, FieldOrProperty, PropertyMirrorWithInheritance } from '../inheritance';
+import { FieldMirrorWithInheritance, FieldOrProperty, PropertyMirrorWithInheritance } from '../../core/adapters/types';
 
 export function declareField(
   markdownFile: MarkdownFile,

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

@@ -2,7 +2,7 @@ import { ConstructorMirror, DocComment } from '@cparra/apex-reflection';
 import { MarkdownFile } from '../markdown-file';
 import { ParameterMirror } from '@cparra/apex-reflection';
 import { addCustomDocCommentAnnotations, addMermaid } from './doc-comment-annotation-util';
-import { MethodMirrorWithInheritance } from '../inheritance';
+import { MethodMirrorWithInheritance } from '../../core/adapters/types';
 
 export function declareMethod(
   markdownFile: MarkdownFile,

package/src/model/markdown-type-file.ts

@@ -11,8 +11,12 @@ import { WalkerListener } from '../service/walkers/walker';
 import { MarkdownFile } from './markdown-file';
 import { declareType, declareMethod, declareField } from './markdown-generation-util';
 import ClassFileGeneratorHelper from '../transpiler/markdown/class-file-generatorHelper';
-import { FieldMirrorWithInheritance, MethodMirrorWithInheritance, PropertyMirrorWithInheritance } from './inheritance';
 import { Settings } from '../settings';
+import {
+  FieldMirrorWithInheritance,
+  MethodMirrorWithInheritance,
+  PropertyMirrorWithInheritance
+} from '../core/adapters/types';
 
 interface GroupAware {
   group?: string;

package/src/service/__tests__/apex-file-reader.spec.ts

@@ -15,6 +15,7 @@ describe('File Reader', () => {
       openApiFileName: 'openapi',
       title: 'Classes',
       includeMetadata: false,
+      linkingStrategy: 'root-relative',
     } as SettingsConfig);
   });
 

package/src/service/apex-file-reader.ts

@@ -1,6 +1,6 @@
 import { Settings } from '../settings';
 import { FileSystem } from './file-system';
-import ApexBundle from '../model/apex-bundle';
+import ApexBundle from '../core/apex-bundle';
 
 const APEX_FILE_EXTENSION = '.cls';
 

package/src/service/manifest-factory.ts

@@ -1,7 +1,7 @@
-import Manifest from '../model/manifest';
+import Manifest from '../core/manifest';
 import { TypeParser } from './parser';
 import { ReflectionResult } from '@cparra/apex-reflection';
-import ApexBundle from '../model/apex-bundle';
+import ApexBundle from '../core/apex-bundle';
 
 /**
  * Builds a new Manifest object, sourcing its types from the received TypeParser.

package/src/service/parser.ts

@@ -1,5 +1,5 @@
 import { ClassMirror, InterfaceMirror, ReflectionResult, Type } from '@cparra/apex-reflection';
-import ApexBundle from '../model/apex-bundle';
+import ApexBundle from '../core/apex-bundle';
 import MetadataProcessor from './metadata-processor';
 import { Logger } from '../util/logger';
 

package/src/settings.ts

@@ -1,4 +1,5 @@
 import { GeneratorChoices } from './transpiler/generator-choices';
+import { LinkingStrategy } from './transpiler/processor-type-transpiler';
 
 export type OnBeforeFileWrite = (file: TargetFile) => TargetFile;
 
@@ -40,6 +41,7 @@ export interface SettingsConfig {
   onAfterProcess?: (files: TargetFile[]) => void;
   onBeforeFileWrite?: (file: TargetFile) => TargetFile;
   frontMatterHeader?: (file: TargetType) => string[];
+  linkingStrategy: LinkingStrategy;
 }
 
 export class Settings {
@@ -144,4 +146,8 @@ export class Settings {
     }
     return [];
   }
+
+  public getLinkingStrategy(): LinkingStrategy {
+    return this.config.linkingStrategy;
+  }
 }

package/src/test-helpers/SettingsBuilder.ts

@@ -19,6 +19,7 @@ export class SettingsBuilder {
       openApiFileName: 'openapi',
       title: 'Classes',
       includeMetadata: false,
+      linkingStrategy: 'root-relative',
     };
   }
 }

package/src/transpiler/factory.ts

@@ -2,7 +2,6 @@ import ProcessorTypeTranspiler from './processor-type-transpiler';
 import { GeneratorChoices } from './generator-choices';
 import { JekyllDocsProcessor } from './markdown/jekyll/jekyll-docsProcessor';
 import DocsifyDocsProcessor from './markdown/docsify/docsify-docs-processor';
-import { PlainMarkdownDocsProcessor } from './markdown/plain-markdown/plain-docsProcessor';
 import { OpenApiDocsProcessor } from './openapi/open-api-docs-processor';
 
 export class TypeTranspilerFactory {
@@ -20,12 +19,11 @@ export class TypeTranspilerFactory {
       case 'docsify':
         this.typeTranspilerCache = new DocsifyDocsProcessor();
         return this.typeTranspilerCache;
-      case 'plain-markdown':
-        this.typeTranspilerCache = new PlainMarkdownDocsProcessor();
-        return this.typeTranspilerCache;
       case 'openapi':
         this.typeTranspilerCache = new OpenApiDocsProcessor();
         return this.typeTranspilerCache;
+      case 'plain-markdown':
+        throw Error('Plain Markdown processor is not supported through this factory anymore.');
       default:
         throw Error('Invalid target generator');
     }

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

@@ -2,8 +2,6 @@ import { Type } from '@cparra/apex-reflection';
 import { TypesRepository } from '../../model/types-repository';
 import { Settings } from '../../settings';
 import State from '../../service/state';
-import { TypeTranspilerFactory } from '../factory';
-import { StringOrLink } from '../../core/renderable/types';
 
 export default class ClassFileGeneratorHelper {
   public static getSanitizedGroup(classModel: Type) {
@@ -32,24 +30,9 @@ export default class ClassFileGeneratorHelper {
     return this.getFileLink(type);
   }
 
-  public static getRenderableLinkByTypeName(typeName: string): StringOrLink {
-    const type = TypesRepository.getInstance().getFromScopedByName(typeName);
-    if (!type) {
-      // If the type is not found, we return the type name as a string.
-      return typeName;
-    }
-
-    const [fullClassName, fileLink] = ClassFileGeneratorHelper.getFileLinkTuple(type);
-    return {
-      title: fullClassName,
-      url: fileLink,
-    };
-  }
-
   private static getDirectoryRoot(classModel: Type) {
     // root-relative links start from the root by using a leading '/'
-    const generator = Settings.getInstance().targetGenerator;
-    if (TypeTranspilerFactory.get(generator).getLinkingStrategy() === 'root-relative') {
+    if (Settings.getInstance().getLinkingStrategy() === 'root-relative') {
       return `/${this.getSanitizedGroup(classModel)}/`;
     }
 

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

@@ -6,7 +6,7 @@ export const constructorsPartialTemplate = `
 {{#> documentablePartialTemplate}}
 
 {{ heading signature.headingLevel signature.heading }}
-{{ code "apex" signature.value }}
+{{ code signature.value }}
 
 {{#if parameters.value}}
 {{ heading parameters.headingLevel parameters.heading }}

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

@@ -3,10 +3,12 @@ export const documentablePartialTemplate = `
 \`{{this}}\`
 {{/each}}
 
-{{withLinks doc.description}}
+{{{renderContent doc.description}}}
 
 {{#each doc.customTags}}
-**{{splitAndCapitalize name}}** {{withLinks description}}
+**{{splitAndCapitalize name}}** 
+
+{{{renderContent description}}}
 
 {{/each}}
 
@@ -14,11 +16,11 @@ export const documentablePartialTemplate = `
 
 {{#if doc.mermaid.value}}
 {{ heading doc.mermaid.headingLevel doc.mermaid.heading }}
-{{code "mermaid" doc.mermaid.value}}
+{{code doc.mermaid.value}}
 {{/if}}
 
 {{#if doc.example.value}}
 {{ heading doc.example.headingLevel doc.example.heading }}
-{{code "apex" doc.example.value}}
+{{code doc.example.value}}
 {{/if}}
 `.trim();

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

@@ -10,7 +10,7 @@ export const fieldsPartialTemplate = `
 {{#> documentablePartialTemplate }}
 
 {{ heading signature.headingLevel signature.heading }}
-{{ code "apex" signature.value }}
+{{ code signature.value }}
 
 {{ heading type.headingLevel type.heading }}
 {{link type.value}}

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

@@ -10,14 +10,14 @@ export const methodsPartialTemplate = `
 {{#> documentablePartialTemplate}}
 
 {{ heading signature.headingLevel signature.heading }}
-{{ code "apex" signature.value }}
+{{ code signature.value }}
 
 {{#if parameters.value}}
 {{ heading parameters.headingLevel parameters.heading }}
 | Name | Type | Description |
 |------|------|-------------|
 {{#each parameters.value}}
-| {{name}} | {{link type}} | {{withLinks description}} |
+| {{name}} | {{link type}} | {{{renderContent description}}} |
 {{/each}}
 {{/if}}
 

package/tsconfig.json

@@ -3,7 +3,7 @@
     "target": "es6",
     "module": "commonjs",
     "declaration": true,
-    "outDir": "./lib",
+    "outDir": "./dist",
     "strict": true,
     "sourceMap": true,
     "esModuleInterop": true,

package/docs/__old/README.md

@@ -1 +0,0 @@
-Go to [docs](/types/README.md) for more information.

package/docs/__old/index.html

@@ -1,22 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <title>Document</title>
-  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
-  <meta name="description" content="Description">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
-  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">
-</head>
-<body>
-  <div id="app"></div>
-  <script>
-    window.$docsify = {
-      name: '',
-      repo: ''
-    }
-  </script>
-  <!-- Docsify v4 -->
-  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
-</body>
-</html>