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)