Skip to content

Commit cc3012a

Browse files
arvarv
committed
Add support for inferring private based on the name
This adds a command line flag called `--infer-private` which is a string (defaults to `^_`) which is used as a regexp for inferring if a name is private or not. For example: ```js /** C */ class C { /** I'm public */ m() {} /** I'm private */ _p() {} } ``` Fixes #436
1 parent 661f5ce commit cc3012a

File tree

10 files changed

+740
-23
lines changed

10 files changed

+740
-23
lines changed

‎docs/USAGE.md

Lines changed: 37 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -18,28 +18,42 @@ Commands:
1818
lint check for common style and uniformity mistakes
1919
readme inject documentation into your README.md
2020

21-
Options:
22-
--help Show help [boolean]
23-
--version Show version number [boolean]
24-
--shallow shallow mode turns off dependency resolution, only processing
25-
the specified files (or the main script specified in
26-
package.json) [boolean] [default: false]
27-
--config, -c configuration file. an array defining explicit sort order
28-
--external a string / glob match pattern that defines which external
29-
modules will be whitelisted and included in the generated
30-
documentation. [default: null]
31-
--extension, -e only input source files matching this extension will be
32-
parsed, this option can be used multiple times.
33-
--polyglot polyglot mode turns off dependency resolution and enables
34-
multi-language support. use this to document c++ [boolean]
35-
--private, -p generate documentation tagged as private
36-
[boolean] [default: false]
37-
--access, -a Include only comments with a given access level, out of
38-
private, protected, public, undefined. By default, public,
39-
protected, and undefined access levels are included
40-
[choices: "public", "private", "protected", "undefined"]
41-
--github, -g infer links to github in documentation [boolean]
21+
Options:
22+
--help Show help [boolean]
23+
--version Show version number [boolean]
24+
--shallow shallow mode turns off dependency resolution, only
25+
processing the specified files (or the main script
26+
specified in package.json) [boolean] [default: false]
27+
--config, -c configuration file. an array defining explicit sort order
28+
--external a string / glob match pattern that defines which external
29+
modules will be whitelisted and included in the generated
30+
documentation. [default: null]
31+
--extension, -e only input source files matching this extension will be
32+
parsed, this option can be used multiple times.
33+
--polyglot polyglot mode turns off dependency resolution and enables
34+
multi-language support. use this to document c++ [boolean]
35+
--private, -p generate documentation tagged as private
36+
[boolean] [default: false]
37+
--access, -a Include only comments with a given access level, out of
38+
private, protected, public, undefined. By default, public,
39+
protected, and undefined access levels are included
40+
[choices: "public", "private", "protected", "undefined"]
41+
--github, -g infer links to github in documentation [boolean]
42+
--infer-private Infer private access based on the name. This is a regular
43+
expression that is used to match the name
44+
[string] [default: "^_"]
45+
--theme, -t specify a theme: this must be a valid theme module
46+
--name project name. by default, inferred from package.json
47+
--watch, -w watch input files and rebuild documentation when they
48+
change [boolean]
49+
--project-version project version. by default, inferred from package.json
50+
--output, -o output location. omit for stdout, otherwise is a filename
51+
for single-file outputs and a directory name for multi-file
52+
outputs like html [default: "stdout"]
53+
--format, -f [choices: "json", "md", "html"] [default: "json"]
4254

43-
Examples:
44-
documentation build foo.js parse documentation in a given file
55+
Examples:
56+
documentation build foo.js -f md > parse documentation in a file and
57+
API.md generate API documentation as
58+
Markdown
4559
```

‎index.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ var fs = require('fs'),
1818
inferProperties = require('./lib/infer/properties'),
1919
inferMembership = require('./lib/infer/membership'),
2020
inferReturn = require('./lib/infer/return'),
21+
inferAccess = require('./lib/infer/access'),
2122
formatLint = require('./lib/lint').formatLint,
2223
lintComments = require('./lib/lint').lintComments;
2324

@@ -150,6 +151,7 @@ function buildSync(indexes, options) {
150151
}, [])
151152
.map(pipeline(
152153
inferName(),
154+
inferAccess(options.inferPrivate),
153155
inferAugments(),
154156
inferKind(),
155157
inferParams(),
@@ -205,6 +207,7 @@ module.exports.lint = function lint(indexes, options, callback) {
205207
.map(pipeline(
206208
lintComments,
207209
inferName(),
210+
inferAccess(options.inferPrivate),
208211
inferAugments(),
209212
inferKind(),
210213
inferParams(),

‎lib/commands/shared_options.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,12 @@ function sharedInputOptions(parser) {
4848
type: 'boolean',
4949
describe: 'infer links to github in documentation',
5050
alias: 'g'
51+
})
52+
.option('infer-private', {
53+
type: 'string',
54+
describe: 'Infer private access based on the name. This is a regular expression that ' +
55+
'is used to match the name',
56+
default: '^_'
5157
});
5258
}
5359

‎lib/infer/access.js

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
'use strict';
2+
3+
var shouldSkipInference = require('./should_skip_inference');
4+
5+
module.exports = function (pattern) {
6+
var re = pattern ? new RegExp(pattern) : /^_/;
7+
8+
/**
9+
* Infers access (only private atm) from the name.
10+
*
11+
* @name inferAccess
12+
* @param {Object} comment parsed comment
13+
* @returns {Object} comment with access inferred
14+
*/
15+
return shouldSkipInference(function inferAccess(comment) {
16+
// This needs to run after inferName beacuse we infer the access based on
17+
// the name.
18+
if (comment.name && comment.access === undefined &&
19+
re && re.test(comment.name)) {
20+
comment.access = 'private';
21+
}
22+
23+
return comment;
24+
});
25+
};

‎test/bin.js

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,29 @@ test('--private flag', function (t) {
228228
}, false);
229229
});
230230

231+
test('--infer-private flag', function (t) {
232+
233+
documentation(['build fixture/infer-private.input.js --infer-private _$'], {}, function (err, data) {
234+
t.error(err);
235+
236+
// This uses JSON.parse with a reviver used as a visitor.
237+
var foundP = false;
238+
JSON.parse(data, function (n, v) {
239+
// Make sure we do not see any names that match `_$` and that we find `_p`.
240+
if (n === 'name') {
241+
t.equal(typeof v, 'string');
242+
t.ok(!/_$/.test(v));
243+
if (v === '_p') {
244+
foundP = true;
245+
}
246+
}
247+
return v;
248+
});
249+
t.ok(foundP);
250+
t.end();
251+
}, false);
252+
});
253+
231254
test('write to file', function (t) {
232255

233256
var dst = path.join(os.tmpdir(), (Date.now() + Math.random()).toString());

‎test/fixture/infer-private.input.js

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
/**
2+
* _p description
3+
*/
4+
function _p() {}
5+
6+
/**
7+
* q_ description
8+
*/
9+
function q_() {}
10+
11+
/** C description */
12+
class C {
13+
/** m description */
14+
m() {}
15+
/** _p description */
16+
_p() {}
17+
/** q_ description */
18+
q_() {}
19+
}

0 commit comments

Comments
 (0)