support additional sorting orders

mmomtchev · anthony-redFox · commit 4225844a0423 · 2021-11-16T15:29:24.000+03:00
diff --git a/__tests__/fixture/sort-order-alpha.input.js b/__tests__/fixture/sort-order-alpha.input.js
@@ -1,4 +1,4 @@
-// Options: {"sortOrder": "alpha"}
+// Options: {"sortOrder": ["alpha"]}
 
 /** */
 function b() {}
diff --git a/__tests__/lib/__snapshots__/sort.js.snap b/__tests__/lib/__snapshots__/sort.js.snap
@@ -38,12 +38,26 @@ Array [
       "sortKey": "b",
     },
     "name": "carrot",
+    "path": Array [
+      Object {
+        "name": "carrot",
+        "scope": "static",
+        "toc": true,
+      },
+    ],
   },
   Object {
     "context": Object {
       "sortKey": "c",
     },
     "name": "bananas",
+    "path": Array [
+      Object {
+        "name": "bananas",
+        "scope": "static",
+        "toc": true,
+      },
+    ],
   },
 ]
 `;
@@ -86,12 +100,26 @@ Array [
       "sortKey": "b",
     },
     "name": "carrot",
+    "path": Array [
+      Object {
+        "name": "carrot",
+        "scope": "static",
+        "toc": true,
+      },
+    ],
   },
   Object {
     "context": Object {
       "sortKey": "c",
     },
     "name": "bananas",
+    "path": Array [
+      Object {
+        "name": "bananas",
+        "scope": "static",
+        "toc": true,
+      },
+    ],
   },
 ]
 `;
@@ -102,13 +130,43 @@ Array [
     "context": Object {
       "sortKey": "a",
     },
+    "kind": "function",
+    "memberof": "classB",
+    "name": "apples",
+  },
+  Object {
+    "context": Object {
+      "sortKey": "c",
+    },
+    "kind": "function",
+    "memberof": "classB",
+    "name": "bananas",
+  },
+  Object {
+    "context": Object {
+      "sortKey": "b",
+    },
+    "memberof": "classB",
+    "name": "carrot",
+  },
+]
+`;
+
+exports[`sort toc with files absolute path 3`] = `
+Array [
+  Object {
+    "context": Object {
+      "sortKey": "a",
+    },
+    "kind": "function",
     "memberof": "classB",
     "name": "apples",
   },
   Object {
     "context": Object {
       "sortKey": "c",
     },
+    "kind": "function",
     "memberof": "classB",
     "name": "bananas",
   },
diff --git a/__tests__/lib/sort.js b/__tests__/lib/sort.js
@@ -5,21 +5,16 @@ import { fileURLToPath } from 'url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-test('sort stream alphanumeric', function () {
-  const apples = { context: { sortKey: 'a' }, name: 'apples' };
-  const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
-  const banana = { context: { sortKey: 'c' }, name: 'bananas' };
-
-  expect(sort([apples, carrot, banana])).toEqual([apples, carrot, banana]);
+const apples = { context: { sortKey: 'a' }, name: 'apples' };
+const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
+const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
 
-  expect(sort([carrot, apples, banana])).toEqual([apples, carrot, banana]);
+test('sort stream alphanumeric', function () {
+  expect(sort([apples, carrot, bananas])).toEqual([apples, carrot, bananas]);
+  expect(sort([carrot, apples, bananas])).toEqual([apples, carrot, bananas]);
 });
 
 test('sort stream with configuration', function () {
-  const apples = { context: { sortKey: 'a' }, name: 'apples' };
-  const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
-  const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
-
   expect(
     sort([apples, carrot, bananas], {
       toc: ['carrot', 'bananas']
@@ -28,10 +23,6 @@ test('sort stream with configuration', function () {
 });
 
 test('sort stream with configuration and a section', function () {
-  const apples = { context: { sortKey: 'a' }, name: 'apples' };
-  const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
-  const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
-
   const section = {
     name: 'This is the banana type',
     description: 'here lies bananas'
@@ -71,10 +62,6 @@ test('sort stream with configuration and a section', function () {
 
 test('sort an already-sorted stream containing a section/description', function () {
   // this happens in the 'serve' task
-  const apples = { context: { sortKey: 'a' }, name: 'apples' };
-  const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
-  const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
-
   const section = {
     name: 'This is the banana type',
     description: 'here lies bananas'
@@ -114,10 +101,6 @@ test('sort an already-sorted stream containing a section/description', function
 });
 
 test('sort toc with files', function () {
-  const apples = { context: { sortKey: 'a' }, name: 'apples' };
-  const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
-  const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
-
   const snowflake = {
     name: 'snowflake',
     file: path.join(__dirname, '../fixture/snowflake.md')
@@ -131,10 +114,6 @@ test('sort toc with files', function () {
 });
 
 test('sort toc with files absolute path', function () {
-  const apples = { context: { sortKey: 'a' }, name: 'apples' };
-  const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
-  const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
-
   const snowflake = {
     name: 'snowflake',
     file: path.join(__dirname, '../fixture/snowflake.md')
@@ -150,6 +129,7 @@ test('sort toc with files absolute path', function () {
   const apples = {
     context: { sortKey: 'a' },
     name: 'apples',
+    kind: 'function',
     memberof: 'classB'
   };
   const carrot = {
@@ -160,6 +140,7 @@ test('sort toc with files absolute path', function () {
   const bananas = {
     context: { sortKey: 'c' },
     name: 'bananas',
+    kind: 'function',
     memberof: 'classB'
   };
 
@@ -169,7 +150,13 @@ test('sort toc with files absolute path', function () {
   };
   expect(
     sort([carrot, apples, bananas], {
-      sortOrder: 'alpha'
+      sortOrder: ['alpha']
+    })
+  ).toMatchSnapshot();
+
+  expect(
+    sort([carrot, apples, bananas], {
+      sortOrder: ['kind', 'alpha']
     })
   ).toMatchSnapshot();
 });
diff --git a/docs/USAGE.md b/docs/USAGE.md
@@ -56,8 +56,10 @@ Options:
   --document-exported        Generate documentation for all exported bindings
                              and members even if there is no JSDoc for them
                                                       [boolean] [default: false]
-  --sort-order               The order to sort the documentation
-                                [choices: "source", "alpha"] [default: "source"]
+  --sort-order               The order to sort the documentation, may be
+                             specified multiple times
+                                [choices: "source", "alpha", "kind"]
+                                                             [default: "source"]
   --output, -o               output location. omit for stdout, otherwise is a
                              filename for single-file outputs and a directory
                              name for multi-file outputs like html
diff --git a/src/commands/shared_options.js b/src/commands/shared_options.js
@@ -74,8 +74,9 @@ export const sharedInputOptions = {
   },
   'sort-order': {
     describe: 'The order to sort the documentation',
-    choices: ['source', 'alpha'],
-    default: 'source'
+    array: true,
+    choices: ['source', 'alpha', 'kind', 'access'],
+    default: ['source']
   },
   resolve: {
     describe: 'Dependency resolution algorithm.',
diff --git a/src/sort.js b/src/sort.js
@@ -103,9 +103,9 @@ export default function (comments, options) {
   return fixed.concat(unfixed);
 }
 
-function compareCommentsByName(a, b) {
-  const akey = a.name;
-  const bkey = b.name;
+function compareCommentsByField(field, a, b) {
+  const akey = a[field];
+  const bkey = b[field];
 
   if (akey && bkey) {
     return akey.localeCompare(bkey, undefined, { caseFirst: 'upper' });
@@ -117,10 +117,19 @@ function compareCommentsBySourceLocation(a, b) {
   return a.context.sortKey.localeCompare(b.context.sortKey);
 }
 
+const sortFns = {
+  alpha: compareCommentsByField.bind(null, 'name'),
+  source: compareCommentsBySourceLocation,
+  kind: compareCommentsByField.bind(null, 'kind'),
+  access: compareCommentsByField.bind(null, 'access')
+};
+
 function sortComments(comments, sortOrder) {
-  return comments.sort(
-    sortOrder === 'alpha'
-      ? compareCommentsByName
-      : compareCommentsBySourceLocation
-  );
+  return comments.sort((a, b) => {
+    for (const sortMethod of sortOrder || ['source']) {
+      const r = sortFns[sortMethod](a, b);
+      if (r !== 0) return r;
+    }
+    return 0;
+  });
 }

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-// Options: {"sortOrder": "alpha"}`
	`1`	`+// Options: {"sortOrder": ["alpha"]}`
`2`	`2`
`3`	`3`	`/** */`
`4`	`4`	`function b() {}`