@cparra/apexdocs 2.22.0 → 2.23.0

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

@@ -8,15 +8,9 @@ export function declareField(
   grouped = false,
 ) {
   markdownFile.addBlankLine();
-  fields
-    .sort((propA, propB) => {
-      if (propA.name < propB.name) return -1;
-      if (propA.name > propB.name) return 1;
-      return 0;
-    })
-    .forEach((propertyModel) => {
-      addFieldSection(markdownFile, propertyModel, startingHeadingLevel, grouped);
-    });
+  fields.forEach((propertyModel) => {
+    addFieldSection(markdownFile, propertyModel, startingHeadingLevel, grouped);
+  });
 
   markdownFile.addHorizontalRule();
 }

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

@@ -91,16 +91,10 @@ export class MarkdownTypeFile extends MarkdownFile implements WalkerListener {
 
   private addInnerTypes(title: string, types: Type[], addSeparator = true) {
     this.addTitle(title, this.headingLevel + 1);
-    types
-      .sort((typeA, typeB) => {
-        if (typeA.name < typeB.name) return -1;
-        if (typeA.name > typeB.name) return 1;
-        return 0;
-      })
-      .forEach((currentType) => {
-        const innerFile = new MarkdownTypeFile(currentType, this.headingLevel + 2, undefined, true);
-        this.addText(innerFile._contents);
-      });
+    types.forEach((currentType) => {
+      const innerFile = new MarkdownTypeFile(currentType, this.headingLevel + 2, undefined, true);
+      this.addText(innerFile._contents);
+    });
     if (addSeparator) {
       this.addHorizontalRule();
     }

package/src/service/walkers/class-walker.ts

@@ -5,27 +5,26 @@ export class ClassWalker extends Walker {
   walk(listener: WalkerListener): void {
     listener.onTypeDeclaration(this.type);
     const classMirror = this.type as ClassMirror;
-
     if (classMirror.constructors.length) {
       listener.onConstructorDeclaration(this.type.name, classMirror.constructors);
     }
     if (classMirror.fields.length) {
-      listener.onFieldsDeclaration(classMirror.fields);
+      listener.onFieldsDeclaration(this.sortType(classMirror.fields));
     }
     if (classMirror.properties.length) {
-      listener.onPropertiesDeclaration(classMirror.properties);
+      listener.onPropertiesDeclaration(this.sortType(classMirror.properties));
     }
     if (classMirror.methods.length) {
-      listener.onMethodsDeclaration(classMirror.methods);
+      listener.onMethodsDeclaration(this.sortType(classMirror.methods));
     }
     if (classMirror.enums.length) {
-      listener.onInnerEnumsDeclaration(classMirror.enums);
+      listener.onInnerEnumsDeclaration(this.sortType(classMirror.enums));
     }
     if (classMirror.classes.length) {
-      listener.onInnerClassesDeclaration(classMirror.classes);
+      listener.onInnerClassesDeclaration(this.sortType(classMirror.classes));
     }
     if (classMirror.interfaces.length) {
-      listener.onInnerInterfacesDeclaration(classMirror.interfaces);
+      listener.onInnerInterfacesDeclaration(this.sortType(classMirror.interfaces));
     }
   }
 }

package/src/service/walkers/enum-walker.ts

@@ -1,5 +1,4 @@
 import { Walker, WalkerListener } from './walker';
-import { EnumMirror } from '@cparra/apex-reflection';
 
 export class EnumWalker extends Walker {
   walk(listener: WalkerListener): void {

package/src/service/walkers/interface-walker.ts

@@ -6,7 +6,7 @@ export class InterfaceWalker extends Walker {
     listener.onTypeDeclaration(this.type);
     const interfaceMirror = this.type as InterfaceMirror;
     if (interfaceMirror.methods.length) {
-      listener.onMethodsDeclaration(interfaceMirror.methods);
+      listener.onMethodsDeclaration(this.sortType(interfaceMirror.methods));
     }
   }
 }

package/src/service/walkers/walker.ts

@@ -8,7 +8,7 @@ import {
   PropertyMirror,
   Type,
 } from '@cparra/apex-reflection';
-import { Annotation } from '@cparra/apex-reflection/index';
+import { Settings } from '../../settings';
 
 export interface WalkerListener {
   onTypeDeclaration(typeMirror: Type): void;
@@ -32,4 +32,11 @@ export abstract class Walker {
   constructor(public type: Type) {}
 
   abstract walk(listener: WalkerListener): void;
+
+  protected sortType<T extends { name: string }>(types: T[]): T[] {
+    if (Settings.getInstance().sortMembersAlphabetically()) {
+      return types.sort((a, b) => a.name.localeCompare(b.name));
+    }
+    return types;
+  }
 }

package/src/settings.ts

@@ -13,6 +13,14 @@ export type OutputDir = {
   fileDir: string;
 };
 
+export type TargetType = {
+  name: string;
+  typeName: 'class' | 'interface' | 'enum';
+  accessModifier: string;
+  description?: string;
+  group?: string;
+};
+
 export interface SettingsConfig {
   sourceDirectory: string;
   recursive: boolean;
@@ -28,8 +36,10 @@ export interface SettingsConfig {
   openApiFileName: string;
   includeMetadata: boolean;
   rootDir?: string;
+  sortMembersAlphabetically?: boolean;
   onAfterProcess?: (files: TargetFile[]) => void;
   onBeforeFileWrite?: (file: TargetFile) => TargetFile;
+  frontMatterHeader?: (file: TargetType) => string[];
 }
 
 export class Settings {
@@ -107,6 +117,10 @@ export class Settings {
     return this.config.includeMetadata;
   }
 
+  public sortMembersAlphabetically(): boolean {
+    return this.config.sortMembersAlphabetically ?? false;
+  }
+
   public getRootDir(): string | undefined {
     return this.config.rootDir;
   }
@@ -123,4 +137,11 @@ export class Settings {
     }
     return file;
   }
+
+  public frontMatterHeader(file: TargetType): string[] {
+    if (this.config.frontMatterHeader) {
+      return this.config.frontMatterHeader(file);
+    }
+    return [];
+  }
 }

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

@@ -40,11 +40,11 @@ export default class ClassFileGeneratorHelper {
         // 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
+        // If the types have different groups, then we have to go up a directory
         return `../${this.getSanitizedGroup(classModel)}/`;
       }
     } else {
-      // If nothing is being processed then we assume we are at the root and links should include the groups
+      // If nothing is being processed, then we assume we are at the root and links should include the groups
       return `./${this.getSanitizedGroup(classModel)}/`;
     }
   }

package/src/transpiler/markdown/jekyll/jekyll-docsProcessor.ts

@@ -3,6 +3,7 @@ import { Type } from '@cparra/apex-reflection';
 import { MarkdownHomeFile } from '../../../model/markdown-home-file';
 import { MarkdownTypeFile } from '../../../model/markdown-type-file';
 import { LinkingStrategy } from '../../processor-type-transpiler';
+import { Settings } from '../../../settings';
 
 export class JekyllDocsProcessor extends MarkdownTranspilerBase {
   homeFileName(): string {
@@ -10,17 +11,39 @@ export class JekyllDocsProcessor extends MarkdownTranspilerBase {
   }
 
   onBeforeProcess = (types: Type[]) => {
-    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types, this.frontMatterHeader));
+    this._fileContainer.pushFile(new MarkdownHomeFile(this.homeFileName(), types, this.frontMatterForHomeFile));
   };
 
   onProcess(type: Type): void {
-    this._fileContainer.pushFile(new MarkdownTypeFile(type, 1, this.frontMatterHeader));
+    this._fileContainer.pushFile(new MarkdownTypeFile(type, 1, this.getFrontMatterHeader(type)));
   }
 
-  get frontMatterHeader(): string {
+  get frontMatterForHomeFile(): string {
     return '---\nlayout: default\n---';
   }
 
+  getFrontMatterHeader(type: Type): string {
+    const headerLines = ['---'];
+    // "layout: default" is a required front matter header for Jekyll
+    headerLines.push('layout: default');
+    // Add any additional front matter headers that might have been configured in the settings
+    const targetType = {
+      name: type.name,
+      typeName: type.type_name,
+      accessModifier: type.access_modifier,
+      group: type.group,
+      description: type.docComment?.description,
+    };
+    const configuredHeaders = Settings.getInstance().frontMatterHeader(targetType);
+    if (configuredHeaders) {
+      configuredHeaders.forEach((header) => {
+        headerLines.push(header);
+      });
+    }
+    headerLines.push('---');
+    return headerLines.join('\n');
+  }
+
   getLinkingStrategy(): LinkingStrategy {
     return 'path-relative';
   }

package/tsconfig.json

@@ -1,20 +1,20 @@
-{
-  "compilerOptions": {
-    "target": "es6",
-    "module": "commonjs",
-    "declaration": true,
-    "outDir": "./lib",
-    "strict": true,
-    "sourceMap": true,
-    "lib": [
-      "ES2021"
-    ]
-  },
-  "include": [
-    "src"
-  ],
-  "exclude": [
-    "node_modules",
-    "**/__tests__/*"
-  ]
-}
+{
+  "compilerOptions": {
+    "target": "es6",
+    "module": "commonjs",
+    "declaration": true,
+    "outDir": "./lib",
+    "strict": true,
+    "sourceMap": true,
+    "lib": [
+      "ES2021"
+    ]
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/__tests__/*"
+  ]
+}

package/tslint.json

@@ -1,6 +1,6 @@
-{
-    "extends": [
-        "tslint:recommended",
-        "tslint-config-prettier"
-    ]
+{
+    "extends": [
+        "tslint:recommended",
+        "tslint-config-prettier"
+    ]
 }

package/ROADMAP.md

@@ -1,16 +0,0 @@
-[ ] Respect access modifiers where the properties/methods are different from the class declaration. For example,
-AuraEnabled properties do not live in an AuraEnabled class, so there's no way to just generate docs to showcase the
-AuraEnabled properties of a class without some sort of combination of also exposing other public/globals
-
-[ ] Versioning capabilities. When creating the doc you specify a version number, and a new directory is created for the
-files, instead of just overriding
-
-[ ] New generatortype: To JsDocs from AuraEnabled
-
-[ ] More unit tests
-
-[ ] config.js support to allow for injections, home header, etc.
-
-[ ] Add configuration setting that allows someone to set the "namespace"
-
-[ ] Homepage support similar to what docsify does