First pass

Author: hsubox76

.changeset/popular-beans-wonder.md

@@ -0,0 +1,5 @@
+---
+'@firebase/api-documenter': minor
+---
+
+Add an option to sort functions by first param. (--sort-functions)

repo-scripts/api-documenter/src/cli/MarkdownAction.ts

@@ -21,8 +21,10 @@
 import { ApiDocumenterCommandLine } from './ApiDocumenterCommandLine';
 import { BaseAction } from './BaseAction';
 import { MarkdownDocumenter } from '../documenters/MarkdownDocumenter';
+import { CommandLineFlagParameter } from '@rushstack/ts-command-line';
 
 export class MarkdownAction extends BaseAction {
+  private _shouldSortFunctions!: CommandLineFlagParameter;
   public constructor(parser: ApiDocumenterCommandLine) {
     super({
       actionName: 'markdown',
@@ -33,10 +35,21 @@ export class MarkdownAction extends BaseAction {
     });
   }
 
+  protected onDefineParameters(): void {
+    super.onDefineParameters();
+
+    this._shouldSortFunctions = this.defineFlagParameter({
+      parameterLongName: '--sort-functions',
+      description:
+        `Sorts functions tables and listings by first parameter.`
+    });
+  }
+
   protected async onExecute(): Promise<void> {
     // override
     const { apiModel, outputFolder, addFileNameSuffix, projectName } =
       this.buildApiModel();
+    const shouldSortFunctions: boolean = this._shouldSortFunctions.value;
 
     if (!projectName) {
       throw new Error('No project name provided. Use --project.');
@@ -47,7 +60,8 @@ export class MarkdownAction extends BaseAction {
       documenterConfig: undefined,
       outputFolder,
       addFileNameSuffix,
-      projectName
+      projectName,
+      shouldSortFunctions
     });
     markdownDocumenter.generateFiles();
   }

repo-scripts/api-documenter/src/documenters/MarkdownDocumenter.ts

@@ -93,6 +93,7 @@ export interface IMarkdownDocumenterOptions {
   outputFolder: string;
   addFileNameSuffix: boolean;
   projectName: string;
+  shouldSortFunctions: boolean;
 }
 
 /**
@@ -108,13 +109,15 @@ export class MarkdownDocumenter {
   private readonly _pluginLoader: PluginLoader;
   private readonly _addFileNameSuffix: boolean;
   private readonly _projectName: string;
+  private readonly _shouldSortFunctions: boolean;
 
   public constructor(options: IMarkdownDocumenterOptions) {
     this._apiModel = options.apiModel;
     this._documenterConfig = options.documenterConfig;
     this._outputFolder = options.outputFolder;
     this._addFileNameSuffix = options.addFileNameSuffix;
     this._projectName = options.projectName;
+    this._shouldSortFunctions = options.shouldSortFunctions;
     this._tsdocConfiguration = CustomDocNodes.configuration;
     this._markdownEmitter = new CustomMarkdownEmitter(this._apiModel);
 
@@ -834,11 +837,13 @@ page_type: reference
       headerTitles: ['Enumeration', 'Description']
     });
 
-    const functionsTable: DocTable = new DocTable({
+    const finalFunctionsTable: DocTable = new DocTable({
       configuration,
       headerTitles: ['Function', 'Description']
     });
 
+    const functionsRowGroup: Record<string, DocTableRow[]> = {};
+
     const interfacesTable: DocTable = new DocTable({
       configuration,
       headerTitles: ['Interface', 'Description']
@@ -859,7 +864,8 @@ page_type: reference
       headerTitles: ['Type Alias', 'Description']
     });
 
-    const functionsDefinitions: DocNode[] = [];
+    const functionsDefinitionsGroup: Record<string, DocNode[]> = {};
+    const finalFunctionsDefinitions: DocNode[] = [];
     const variablesDefinitions: DocNode[] = [];
     const typeAliasDefinitions: DocNode[] = [];
     const enumsDefinitions: DocNode[] = [];
@@ -899,10 +905,24 @@ page_type: reference
           break;
 
         case ApiItemKind.Function:
-          functionsTable.addRow(row);
-          functionsDefinitions.push(
-            ...this._createCompleteOutputForApiItem(apiMember)
-          );
+          if (this._shouldSortFunctions) {
+            const firstParam = (apiMember as ApiParameterListMixin).parameters[0] || { name : '' };
+            if (!functionsRowGroup[firstParam.name]) {
+              functionsRowGroup[firstParam.name] = [];
+            }
+            if (!functionsDefinitionsGroup[firstParam.name]) {
+              functionsDefinitionsGroup[firstParam.name] = [];
+            }
+            functionsRowGroup[firstParam.name].push(row);
+            functionsDefinitionsGroup[firstParam.name].push(
+              ...this._createCompleteOutputForApiItem(apiMember)
+            );
+          } else {
+            finalFunctionsTable.addRow(row);
+            finalFunctionsDefinitions.push(
+              ...this._createCompleteOutputForApiItem(apiMember)
+            );
+          }
           break;
 
         case ApiItemKind.TypeAlias:
@@ -921,9 +941,30 @@ page_type: reference
       }
     }
 
-    if (functionsTable.rows.length > 0) {
+    if (this._shouldSortFunctions) {
+      const sortedFunctionsFirstParamKeys = Object.keys(functionsRowGroup).sort((a, b) => {
+        if (a === 'app') {
+          return -1;
+        }
+        return (a.localeCompare(b));
+      });
+  
+      for (const paramKey of sortedFunctionsFirstParamKeys) {
+        if (finalFunctionsTable.rows.length > 0) {
+          finalFunctionsTable.createAndAddRow();
+        }
+        for (const functionsRow of functionsRowGroup[paramKey]) {
+          finalFunctionsTable.addRow(functionsRow);
+        }
+        for (const functionDefinition of functionsDefinitionsGroup[paramKey]) {
+          finalFunctionsDefinitions.push(functionDefinition);
+        }
+      }
+    }
+
+    if (finalFunctionsTable.rows.length > 0) {
       output.push(new DocHeading({ configuration, title: 'Functions' }));
-      output.push(functionsTable);
+      output.push(finalFunctionsTable);
     }
 
     if (classesTable.rows.length > 0) {
@@ -956,8 +997,8 @@ page_type: reference
       output.push(typeAliasesTable);
     }
 
-    if (functionsDefinitions.length > 0) {
-      output.push(...functionsDefinitions);
+    if (finalFunctionsDefinitions.length > 0) {
+      output.push(...finalFunctionsDefinitions);
     }
 
     if (variablesDefinitions.length > 0) {

scripts/docgen/docgen.ts

@@ -181,7 +181,8 @@ async function generateDocs(
       '--output',
       outputFolder,
       '--project',
-      'js'
+      'js',
+      '--sort-functions'
     ],
     { stdio: 'inherit' }
   );