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

package/src/application/Apexdocs.ts

@@ -12,6 +12,7 @@ import ApexBundle from '../model/apex-bundle';
 import Manifest from '../model/manifest';
 import { TypesRepository } from '../model/types-repository';
 import { TypeTranspilerFactory } from '../transpiler/factory';
+import { generateMarkdownFiles } from './flows/generate-markdown-files';
 
 /**
  * Application entry-point to generate documentation out of Apex source files.
@@ -23,24 +24,29 @@ export class Apexdocs {
   static generate(): void {
     Logger.log('Initializing...');
     const fileBodies = ApexFileReader.processFiles(new DefaultFileSystem());
-    const manifest = createManifest(new RawBodyParser(fileBodies), this._reflectionWithLogger);
-    TypesRepository.getInstance().populateAll(manifest.types);
-    const filteredTypes = this.filterByScopes(manifest);
-    TypesRepository.getInstance().populateScoped(filteredTypes);
-    const processor = TypeTranspilerFactory.get(Settings.getInstance().targetGenerator);
-    Transpiler.generate(filteredTypes, processor);
-    const generatedFiles = processor.fileBuilder().files();
 
-    const files: TargetFile[] = [];
-    FileWriter.write(generatedFiles, (file: TargetFile) => {
-      Logger.logSingle(`${file.name} processed.`, false, 'green', false);
-      files.push(file);
-    });
+    if (Settings.getInstance().targetGenerator === 'plain-markdown') {
+      generateMarkdownFiles(fileBodies);
+    } else {
+      const manifest = createManifest(new RawBodyParser(fileBodies), this._reflectionWithLogger);
+      TypesRepository.getInstance().populateAll(manifest.types);
+      const filteredTypes = this.filterByScopes(manifest);
+      TypesRepository.getInstance().populateScoped(filteredTypes);
+      const processor = TypeTranspilerFactory.get(Settings.getInstance().targetGenerator);
+      Transpiler.generate(filteredTypes, processor);
+      const generatedFiles = processor.fileBuilder().files();
+
+      const files: TargetFile[] = [];
+      FileWriter.write(generatedFiles, (file: TargetFile) => {
+        Logger.logSingle(`${file.name} processed.`, false, 'green', false);
+        files.push(file);
+      });
 
-    Settings.getInstance().onAfterProcess(files);
+      Settings.getInstance().onAfterProcess(files);
 
-    // Error logging
-    ErrorLogger.logErrors(filteredTypes);
+      // Error logging
+      ErrorLogger.logErrors(filteredTypes);
+    }
   }
 
   private static filterByScopes(manifest: Manifest) {

package/src/application/flows/generate-markdown-files.ts

@@ -0,0 +1,47 @@
+import ApexBundle from '../../model/apex-bundle';
+import { Settings, TargetFile } from '../../settings';
+import { DocumentationBundle, generateDocs } from '../../core/generate-docs';
+import { MarkdownFile } from '../../model/markdown-file';
+import { FileWriter } from '../../service/file-writer';
+import { Logger } from '../../util/logger';
+import { flow } from 'fp-ts/function';
+import * as E from 'fp-ts/Either';
+
+export const generateMarkdownFiles = flow(
+  generateDocumentationBundle,
+  E.map(convertToMarkdownFiles),
+  E.map(writeFilesToSystem),
+  E.mapLeft((errors) => {
+    Logger.error(errors.join('\n'));
+  }),
+);
+
+function generateDocumentationBundle(bundles: ApexBundle[]) {
+  return generateDocs(
+    bundles.map((file) => file.rawTypeContent),
+    {
+      scope: Settings.getInstance().scope,
+      outputDir: Settings.getInstance().outputDir,
+      namespace: Settings.getInstance().getNamespace(),
+      sortMembersAlphabetically: Settings.getInstance().sortMembersAlphabetically(),
+      defaultGroupName: Settings.getInstance().getDefaultGroupName(),
+    },
+  );
+}
+
+function convertToMarkdownFiles(docBundle: DocumentationBundle): MarkdownFile[] {
+  return [
+    new MarkdownFile('index', '').addText(docBundle.referenceGuide),
+    ...docBundle.docs.map((doc) =>
+      new MarkdownFile(`${Settings.getInstance().getNamespacePrefix()}${doc.typeName}`, doc.directory).addText(
+        doc.docContents,
+      ),
+    ),
+  ];
+}
+
+function writeFilesToSystem(files: MarkdownFile[]) {
+  FileWriter.write(files, (file: TargetFile) => {
+    Logger.logSingle(`${file.name} processed.`, false, 'green', false);
+  });
+}

package/src/core/__test__/inheritance-chain.test.ts

@@ -0,0 +1,54 @@
+import { ClassMirrorBuilder } from '../../test-helpers/ClassMirrorBuilder';
+import { createInheritanceChain } from '../inheritance-chain';
+
+describe('inheritance chain for classes', () => {
+  test('returns an empty list of the class does not extend any other class', () => {
+    const classMirror = new ClassMirrorBuilder().build();
+    const repository = [classMirror];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual([]);
+  });
+
+  test('returns the name of the extended class if it is not found in the repository', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const repository = [classMirror];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass']);
+  });
+
+  test('returns the extended class when it is present in the repository', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').build();
+    const repository = [classMirror, extendedClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass']);
+  });
+
+  test('returns the full inheritance chain when the extended class is also extended', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('ExtendedClass').build();
+    const extendedClass = new ClassMirrorBuilder().withName('ExtendedClass').withExtendedClass('SuperClass').build();
+    const superClass = new ClassMirrorBuilder().withName('SuperClass').build();
+    const repository = [classMirror, extendedClass, superClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['ExtendedClass', 'SuperClass']);
+  });
+
+  test('returns the inheritance for a class that extends an inner class', () => {
+    const classMirror = new ClassMirrorBuilder().withExtendedClass('OuterClass.InnerClass').build();
+    const innerClass = new ClassMirrorBuilder().withName('InnerClass').build();
+    const outerClass = new ClassMirrorBuilder().withName('OuterClass').addInnerClass(innerClass).build();
+    const repository = [classMirror, outerClass];
+
+    const inheritanceChain = createInheritanceChain(repository, classMirror);
+
+    expect(inheritanceChain).toEqual(['OuterClass.InnerClass']);
+  });
+});

package/src/core/generate-docs.ts

@@ -1,6 +1,6 @@
 import { ClassMirror, InterfaceMirror, reflect as mirrorReflection, Type } from '@cparra/apex-reflection';
 import { typeToRenderableType } from '../adapters/apex-types';
-import { Renderable, RenderableContent, RenderableEnum, StringOrLink } from './renderable/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';
@@ -10,6 +10,7 @@ import { CompilationRequest, Template } from './template';
 import Manifest from '../model/manifest';
 import { referenceGuideTemplate } from './templates/reference-guide';
 import { adaptDescribable } from '../adapters/documentables';
+import { createInheritanceChain } from './inheritance-chain';
 
 export const documentType = flow(typeToRenderableType, resolveApexTypeTemplate, compile);
 
@@ -29,6 +30,7 @@ type DocumentationConfig = {
 };
 
 type DocOutput = {
+  directory: string;
   docContents: string;
   typeName: string;
   type: 'class' | 'interface' | 'enum';
@@ -50,19 +52,22 @@ export function generateDocs(
     input,
     (input) => input.map(reflectSourceBody),
     checkForReflectionErrors,
-    E.map((types) => types.map((type) => addInheritedMembers(type, types))),
     E.map((types) => filterTypesOutOfScope(types, configWithDefaults.scope)),
+    E.map((types) => types.map((type) => addInheritedMembers(type, types))),
+    E.map((types) => types.map((type) => addInheritanceChain(type, types))),
     E.map((types) => typesToRenderableBundle(types, configWithDefaults)),
     E.map(({ references, renderables }) => ({
       referenceGuide: pipe(referencesToReferenceGuide(references, configWithDefaults.referenceGuideTemplate)),
-      docs: renderables.map(renderableToOutputDoc),
+      docs: renderables.map((renderable) => renderableToOutputDoc(Object.values(references).flat(), renderable)),
     })),
     E.map(({ referenceGuide, docs }) => ({ format: 'markdown', referenceGuide: referenceGuide, docs })),
   );
 }
 
 type ReferenceGuideReference = {
-  title: StringOrLink;
+  typeName: string;
+  directory: string;
+  title: Link;
   description: RenderableContent[] | undefined;
 };
 
@@ -88,11 +93,12 @@ function typesToRenderableBundle(types: Type[], config: DocumentationConfig) {
 
       const descriptionLines = type.docComment?.descriptionLines;
       const reference = {
+        typeName: type.name,
+        directory: getDirectoryFromRoot(config, type),
         title: getLinkFromRoot(config, type),
-        description: adaptDescribable(descriptionLines, (referenceName) => {
-          const type = findType(types, referenceName);
-          return type ? getLinkFromRoot(config, type) : referenceName;
-        }).description,
+        description: adaptDescribable(descriptionLines, (referenceName) =>
+          getPossibleLinkFromRoot(config, referenceName, findType(types, referenceName)),
+        ).description,
       };
 
       const group = getTypeGroup(type, config);
@@ -110,9 +116,13 @@ function typesToRenderableBundle(types: Type[], config: DocumentationConfig) {
   );
 }
 
-function renderableToOutputDoc(renderable: Renderable): DocOutput {
+function renderableToOutputDoc(referenceGuideReference: ReferenceGuideReference[], renderable: Renderable): DocOutput {
   function buildDocOutput(renderable: Renderable, docContents: string): DocOutput {
+    const reference = referenceGuideReference.find(
+      (ref) => ref.typeName.toLowerCase() === renderable.name.toLowerCase(),
+    );
     return {
+      directory: reference!.directory,
       docContents,
       typeName: renderable.name,
       type: renderable.type,
@@ -213,6 +223,18 @@ function addInheritedMembers<T extends Type>(current: T, repository: Type[]): T
   }
 }
 
+function addInheritanceChain<T extends Type>(current: T, repository: Type[]): T {
+  if (current.type_name === 'enum' || current.type_name === 'interface') {
+    return current;
+  } else {
+    const inheritanceChain = createInheritanceChain(repository, current as ClassMirror);
+    return {
+      ...current,
+      inheritanceChain,
+    };
+  }
+}
+
 function getParents<T extends Type>(
   extendedNamesExtractor: (current: T) => string[],
   current: T,
@@ -326,14 +348,31 @@ function getFileLinkTuple(
   return [fullClassName, `${directoryRoot}${fullClassName}.md`];
 }
 
-function getLinkFromRoot(config: DocumentationConfig, type?: Type): StringOrLink {
+function getDirectoryFromRoot(config: DocumentationConfig, type?: Type): string {
   if (!type) {
     return '';
   }
-  const namespacePrefix = config.namespace ? `${config.namespace}./` : '';
+  return `./${getSanitizedGroup(type, config)}`;
+}
+
+function getPossibleLinkFromRoot(config: DocumentationConfig, fallback: string, type?: Type): StringOrLink {
+  if (!type) {
+    return fallback;
+  }
+  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
+  const title = `${namespacePrefix}${type.name}`;
+  return {
+    title: title,
+    url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
+  };
+}
+
+function getLinkFromRoot(config: DocumentationConfig, type: Type): Link {
+  const namespacePrefix = config.namespace ? `${config.namespace}.` : '';
+  const title = `${namespacePrefix}${type.name}`;
   return {
-    title: `${namespacePrefix}${type.name}`,
-    url: `./${namespacePrefix}${getSanitizedGroup(type, config)}/${type.name}.md`,
+    title: title,
+    url: `${getDirectoryFromRoot(config, type)}/${title}.md`,
   };
 }
 

package/src/core/inheritance-chain.ts

@@ -0,0 +1,23 @@
+import { ClassMirror, Type } from '@cparra/apex-reflection';
+import { pipe } from 'fp-ts/function';
+import * as O from 'fp-ts/Option';
+
+export function createInheritanceChain(repository: Type[], classMirror: ClassMirror): string[] {
+  return pipe(
+    O.fromNullable(classMirror.extended_class),
+    O.match(
+      () => [],
+      (extendedClassName) => inheritanceChainFromParentClassName(repository, extendedClassName),
+    ),
+  );
+}
+
+function inheritanceChainFromParentClassName(repository: Type[], className: string): string[] {
+  return pipe(
+    O.fromNullable(repository.find((type) => type.name.toLowerCase() === className.toLowerCase())),
+    O.match(
+      () => [className],
+      (extendedClass: Type) => [className, ...createInheritanceChain(repository, extendedClass as ClassMirror)],
+    ),
+  );
+}

package/src/core/renderable/types.d.ts

@@ -102,7 +102,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;

package/src/model/inheritance.ts

@@ -1,6 +1,7 @@
-import { FieldMirror, MethodMirror, PropertyMirror } from '@cparra/apex-reflection';
+import { ClassMirror, FieldMirror, MethodMirror, PropertyMirror } from '@cparra/apex-reflection';
 
 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;

package/src/model/markdown-file.ts

@@ -19,8 +19,8 @@ export class MarkdownFile extends OutputFile {
   }
 
   public addText(text: string) {
-    //super.addText(this._replaceInlineReferences(text), encodeHtml);
     super.addText(text);
+    return this;
   }
 
   public addLink(text: string) {

package/src/test-helpers/ClassMirrorBuilder.ts

@@ -10,6 +10,8 @@ export class ClassMirrorBuilder {
   private docComment?: DocComment;
   private methods: MethodMirror[] = [];
   private fields: FieldMirror[] = [];
+  private innerClasses: ClassMirror[] = [];
+  private extendedClass: string | undefined;
 
   withName(name: string): ClassMirrorBuilder {
     this.name = name;
@@ -36,6 +38,16 @@ export class ClassMirrorBuilder {
     return this;
   }
 
+  addInnerClass(innerClass: ClassMirror): ClassMirrorBuilder {
+    this.innerClasses.push(innerClass);
+    return this;
+  }
+
+  withExtendedClass(extendedClass: string): ClassMirrorBuilder {
+    this.extendedClass = extendedClass;
+    return this;
+  }
+
   build(): ClassMirror {
     return {
       annotations: this.annotations,
@@ -48,9 +60,10 @@ export class ClassMirrorBuilder {
       constructors: [],
       enums: [],
       interfaces: [],
-      classes: [],
+      classes: this.innerClasses,
       access_modifier: 'public',
       docComment: this.docComment,
+      extended_class: this.extendedClass,
     };
   }
 }

package/src/transpiler/markdown/plain-markdown/class-template.ts

@@ -6,9 +6,9 @@ export const classMarkdownTemplate = `
 
 {{> typeDocumentation}}
 
-{{#if extends}}
-**Extends**
-{{link extends}}
+{{#if extends.length}}
+**Inheritance**
+{{#each extends}}{{link this}}{{#unless @last}} < {{/unless}}{{/each}}
 {{/if}}
 
 {{#if implements}}

package/src/util/logger.ts

@@ -5,7 +5,7 @@ import logUpdate from 'log-update';
  * Logs messages to the console.
  */
 export class Logger {
-  static currentFrame = -1;
+  static currentFrame = 0;
 
   static frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];