Skip to content

Commit 4225844

Browse files
mmomtchevanthony-redFox
mmomtchev
authored and
anthony-redFox
committed
support additional sorting orders
1 parent 76c7788 commit 4225844

File tree

6 files changed

+98
-41
lines changed

6 files changed

+98
-41
lines changed

‎__tests__/fixture/sort-order-alpha.input.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Options: {"sortOrder": "alpha"}
1+
// Options: {"sortOrder": ["alpha"]}
22

33
/** */
44
function b() {}

‎__tests__/lib/__snapshots__/sort.js.snap

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,12 +38,26 @@ Array [
3838
"sortKey": "b",
3939
},
4040
"name": "carrot",
41+
"path": Array [
42+
Object {
43+
"name": "carrot",
44+
"scope": "static",
45+
"toc": true,
46+
},
47+
],
4148
},
4249
Object {
4350
"context": Object {
4451
"sortKey": "c",
4552
},
4653
"name": "bananas",
54+
"path": Array [
55+
Object {
56+
"name": "bananas",
57+
"scope": "static",
58+
"toc": true,
59+
},
60+
],
4761
},
4862
]
4963
`;
@@ -86,12 +100,26 @@ Array [
86100
"sortKey": "b",
87101
},
88102
"name": "carrot",
103+
"path": Array [
104+
Object {
105+
"name": "carrot",
106+
"scope": "static",
107+
"toc": true,
108+
},
109+
],
89110
},
90111
Object {
91112
"context": Object {
92113
"sortKey": "c",
93114
},
94115
"name": "bananas",
116+
"path": Array [
117+
Object {
118+
"name": "bananas",
119+
"scope": "static",
120+
"toc": true,
121+
},
122+
],
95123
},
96124
]
97125
`;
@@ -102,13 +130,43 @@ Array [
102130
"context": Object {
103131
"sortKey": "a",
104132
},
133+
"kind": "function",
134+
"memberof": "classB",
135+
"name": "apples",
136+
},
137+
Object {
138+
"context": Object {
139+
"sortKey": "c",
140+
},
141+
"kind": "function",
142+
"memberof": "classB",
143+
"name": "bananas",
144+
},
145+
Object {
146+
"context": Object {
147+
"sortKey": "b",
148+
},
149+
"memberof": "classB",
150+
"name": "carrot",
151+
},
152+
]
153+
`;
154+
155+
exports[`sort toc with files absolute path 3`] = `
156+
Array [
157+
Object {
158+
"context": Object {
159+
"sortKey": "a",
160+
},
161+
"kind": "function",
105162
"memberof": "classB",
106163
"name": "apples",
107164
},
108165
Object {
109166
"context": Object {
110167
"sortKey": "c",
111168
},
169+
"kind": "function",
112170
"memberof": "classB",
113171
"name": "bananas",
114172
},

‎__tests__/lib/sort.js

Lines changed: 15 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,16 @@ import { fileURLToPath } from 'url';
55
const __filename = fileURLToPath(import.meta.url);
66
const __dirname = path.dirname(__filename);
77

8-
test('sort stream alphanumeric', function () {
9-
const apples = { context: { sortKey: 'a' }, name: 'apples' };
10-
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
11-
const banana = { context: { sortKey: 'c' }, name: 'bananas' };
12-
13-
expect(sort([apples, carrot, banana])).toEqual([apples, carrot, banana]);
8+
const apples = { context: { sortKey: 'a' }, name: 'apples' };
9+
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
10+
const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
1411

15-
expect(sort([carrot, apples, banana])).toEqual([apples, carrot, banana]);
12+
test('sort stream alphanumeric', function () {
13+
expect(sort([apples, carrot, bananas])).toEqual([apples, carrot, bananas]);
14+
expect(sort([carrot, apples, bananas])).toEqual([apples, carrot, bananas]);
1615
});
1716

1817
test('sort stream with configuration', function () {
19-
const apples = { context: { sortKey: 'a' }, name: 'apples' };
20-
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
21-
const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
22-
2318
expect(
2419
sort([apples, carrot, bananas], {
2520
toc: ['carrot', 'bananas']
@@ -28,10 +23,6 @@ test('sort stream with configuration', function () {
2823
});
2924

3025
test('sort stream with configuration and a section', function () {
31-
const apples = { context: { sortKey: 'a' }, name: 'apples' };
32-
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
33-
const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
34-
3526
const section = {
3627
name: 'This is the banana type',
3728
description: 'here lies bananas'
@@ -71,10 +62,6 @@ test('sort stream with configuration and a section', function () {
7162

7263
test('sort an already-sorted stream containing a section/description', function () {
7364
// this happens in the 'serve' task
74-
const apples = { context: { sortKey: 'a' }, name: 'apples' };
75-
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
76-
const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
77-
7865
const section = {
7966
name: 'This is the banana type',
8067
description: 'here lies bananas'
@@ -114,10 +101,6 @@ test('sort an already-sorted stream containing a section/description', function
114101
});
115102

116103
test('sort toc with files', function () {
117-
const apples = { context: { sortKey: 'a' }, name: 'apples' };
118-
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
119-
const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
120-
121104
const snowflake = {
122105
name: 'snowflake',
123106
file: path.join(__dirname, '../fixture/snowflake.md')
@@ -131,10 +114,6 @@ test('sort toc with files', function () {
131114
});
132115

133116
test('sort toc with files absolute path', function () {
134-
const apples = { context: { sortKey: 'a' }, name: 'apples' };
135-
const carrot = { context: { sortKey: 'b' }, name: 'carrot' };
136-
const bananas = { context: { sortKey: 'c' }, name: 'bananas' };
137-
138117
const snowflake = {
139118
name: 'snowflake',
140119
file: path.join(__dirname, '../fixture/snowflake.md')
@@ -150,6 +129,7 @@ test('sort toc with files absolute path', function () {
150129
const apples = {
151130
context: { sortKey: 'a' },
152131
name: 'apples',
132+
kind: 'function',
153133
memberof: 'classB'
154134
};
155135
const carrot = {
@@ -160,6 +140,7 @@ test('sort toc with files absolute path', function () {
160140
const bananas = {
161141
context: { sortKey: 'c' },
162142
name: 'bananas',
143+
kind: 'function',
163144
memberof: 'classB'
164145
};
165146

@@ -169,7 +150,13 @@ test('sort toc with files absolute path', function () {
169150
};
170151
expect(
171152
sort([carrot, apples, bananas], {
172-
sortOrder: 'alpha'
153+
sortOrder: ['alpha']
154+
})
155+
).toMatchSnapshot();
156+
157+
expect(
158+
sort([carrot, apples, bananas], {
159+
sortOrder: ['kind', 'alpha']
173160
})
174161
).toMatchSnapshot();
175162
});

‎docs/USAGE.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,10 @@ Options:
5656
--document-exported Generate documentation for all exported bindings
5757
and members even if there is no JSDoc for them
5858
[boolean] [default: false]
59-
--sort-order The order to sort the documentation
60-
[choices: "source", "alpha"] [default: "source"]
59+
--sort-order The order to sort the documentation, may be
60+
specified multiple times
61+
[choices: "source", "alpha", "kind"]
62+
[default: "source"]
6163
--output, -o output location. omit for stdout, otherwise is a
6264
filename for single-file outputs and a directory
6365
name for multi-file outputs like html

‎src/commands/shared_options.js

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,8 +74,9 @@ export const sharedInputOptions = {
7474
},
7575
'sort-order': {
7676
describe: 'The order to sort the documentation',
77-
choices: ['source', 'alpha'],
78-
default: 'source'
77+
array: true,
78+
choices: ['source', 'alpha', 'kind', 'access'],
79+
default: ['source']
7980
},
8081
resolve: {
8182
describe: 'Dependency resolution algorithm.',

‎src/sort.js

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -103,9 +103,9 @@ export default function (comments, options) {
103103
return fixed.concat(unfixed);
104104
}
105105

106-
function compareCommentsByName(a, b) {
107-
const akey = a.name;
108-
const bkey = b.name;
106+
function compareCommentsByField(field, a, b) {
107+
const akey = a[field];
108+
const bkey = b[field];
109109

110110
if (akey && bkey) {
111111
return akey.localeCompare(bkey, undefined, { caseFirst: 'upper' });
@@ -117,10 +117,19 @@ function compareCommentsBySourceLocation(a, b) {
117117
return a.context.sortKey.localeCompare(b.context.sortKey);
118118
}
119119

120+
const sortFns = {
121+
alpha: compareCommentsByField.bind(null, 'name'),
122+
source: compareCommentsBySourceLocation,
123+
kind: compareCommentsByField.bind(null, 'kind'),
124+
access: compareCommentsByField.bind(null, 'access')
125+
};
126+
120127
function sortComments(comments, sortOrder) {
121-
return comments.sort(
122-
sortOrder === 'alpha'
123-
? compareCommentsByName
124-
: compareCommentsBySourceLocation
125-
);
128+
return comments.sort((a, b) => {
129+
for (const sortMethod of sortOrder || ['source']) {
130+
const r = sortFns[sortMethod](a, b);
131+
if (r !== 0) return r;
132+
}
133+
return 0;
134+
});
126135
}

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy