Skip to content

Commit 3053f3e

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 3053f3e

9 files changed

+421
-23
lines changed

Diff for: ‎docs/USAGE.md

+37-23
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
```

Diff for: ‎index.js

+3
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(),

Diff for: ‎lib/commands/shared_options.js

+6
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

Diff for: ‎lib/infer/access.js

+25
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+
};

Diff for: ‎test/fixture/infer-private.input.js

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
/**
2+
* This is inferred to be private.
3+
*/
4+
function _p() {}
5+
6+
/** C */
7+
class C {
8+
/** m */
9+
m() {}
10+
/** This is also inferred to be private. */
11+
_p() {}
12+
}

Diff for: ‎test/fixture/infer-private.output.json

+195
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,195 @@
1+
[
2+
{
3+
"context": {
4+
"code": "/**\n * This is inferred to be private.\n */\nfunction _p() {}\n\n/** C */\nclass C {\n /** m */\n m() {}\n /** This is also inferred to be private. */\n _p() {}\n}\n",
5+
"loc": {
6+
"end": {
7+
"column": 1,
8+
"line": 12
9+
},
10+
"start": {
11+
"column": 0,
12+
"line": 7
13+
}
14+
}
15+
},
16+
"description": {
17+
"children": [
18+
{
19+
"children": [
20+
{
21+
"position": {
22+
"end": {
23+
"column": 2,
24+
"line": 1,
25+
"offset": 1
26+
},
27+
"indent": [],
28+
"start": {
29+
"column": 1,
30+
"line": 1,
31+
"offset": 0
32+
}
33+
},
34+
"type": "text",
35+
"value": "C"
36+
}
37+
],
38+
"position": {
39+
"end": {
40+
"column": 2,
41+
"line": 1,
42+
"offset": 1
43+
},
44+
"indent": [],
45+
"start": {
46+
"column": 1,
47+
"line": 1,
48+
"offset": 0
49+
}
50+
},
51+
"type": "paragraph"
52+
}
53+
],
54+
"position": {
55+
"end": {
56+
"column": 2,
57+
"line": 1,
58+
"offset": 1
59+
},
60+
"start": {
61+
"column": 1,
62+
"line": 1,
63+
"offset": 0
64+
}
65+
},
66+
"type": "root"
67+
},
68+
"errors": [],
69+
"kind": "class",
70+
"loc": {
71+
"end": {
72+
"column": 8,
73+
"line": 6
74+
},
75+
"start": {
76+
"column": 0,
77+
"line": 6
78+
}
79+
},
80+
"members": {
81+
"events": [],
82+
"instance": [
83+
{
84+
"context": {
85+
"code": "/**\n * This is inferred to be private.\n */\nfunction _p() {}\n\n/** C */\nclass C {\n /** m */\n m() {}\n /** This is also inferred to be private. */\n _p() {}\n}\n",
86+
"loc": {
87+
"end": {
88+
"column": 8,
89+
"line": 9
90+
},
91+
"start": {
92+
"column": 2,
93+
"line": 9
94+
}
95+
}
96+
},
97+
"description": {
98+
"children": [
99+
{
100+
"children": [
101+
{
102+
"position": {
103+
"end": {
104+
"column": 2,
105+
"line": 1,
106+
"offset": 1
107+
},
108+
"indent": [],
109+
"start": {
110+
"column": 1,
111+
"line": 1,
112+
"offset": 0
113+
}
114+
},
115+
"type": "text",
116+
"value": "m"
117+
}
118+
],
119+
"position": {
120+
"end": {
121+
"column": 2,
122+
"line": 1,
123+
"offset": 1
124+
},
125+
"indent": [],
126+
"start": {
127+
"column": 1,
128+
"line": 1,
129+
"offset": 0
130+
}
131+
},
132+
"type": "paragraph"
133+
}
134+
],
135+
"position": {
136+
"end": {
137+
"column": 2,
138+
"line": 1,
139+
"offset": 1
140+
},
141+
"start": {
142+
"column": 1,
143+
"line": 1,
144+
"offset": 0
145+
}
146+
},
147+
"type": "root"
148+
},
149+
"errors": [],
150+
"kind": "function",
151+
"loc": {
152+
"end": {
153+
"column": 10,
154+
"line": 8
155+
},
156+
"start": {
157+
"column": 2,
158+
"line": 8
159+
}
160+
},
161+
"memberof": "C",
162+
"members": {
163+
"instance": [],
164+
"static": []
165+
},
166+
"name": "m",
167+
"namespace": "C#m",
168+
"path": [
169+
{
170+
"kind": "class",
171+
"name": "C"
172+
},
173+
{
174+
"kind": "function",
175+
"name": "m",
176+
"scope": "instance"
177+
}
178+
],
179+
"scope": "instance",
180+
"tags": []
181+
}
182+
],
183+
"static": []
184+
},
185+
"name": "C",
186+
"namespace": "C",
187+
"path": [
188+
{
189+
"kind": "class",
190+
"name": "C"
191+
}
192+
],
193+
"tags": []
194+
}
195+
]

Diff for: ‎test/fixture/infer-private.output.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# C
2+
3+
C
4+
5+
## m
6+
7+
m

0 commit comments

Comments
 (0)