Skip to content

Commit 8cc34b6

Browse files
tmcwtmcw
authored
fix(scopes): Support inner scope (#665)
* fix(scopes): Support inner scope The purpose and usage of inner is still unclear, unfortunately, so this is an interim fix at best. Fixes #652 * Improve comment typedef while we're at it
1 parent 8295363 commit 8cc34b6

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+678
-328
lines changed

‎declarations/comment.js

+28-5
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,9 @@ declare type CommentTag = {
7171
declare type CommentMembers = {
7272
static: Array<Comment>,
7373
instance: Array<Comment>,
74-
events: Array<Comment>
74+
events: Array<Comment>,
75+
global: Array<Comment>,
76+
inner: Array<Comment>
7577
};
7678

7779
declare type CommentExample = {
@@ -84,6 +86,20 @@ declare type Remark = {
8486
children: Array<Object>
8587
};
8688

89+
declare type Access = 'private' | 'public' | 'protected';
90+
declare type Scope = 'instance' | 'static' | 'inner' | 'global';
91+
declare type Kind = 'class' |
92+
'constant' |
93+
'event' |
94+
'external' |
95+
'file' |
96+
'function' |
97+
'member' |
98+
'mixin' |
99+
'module' |
100+
'namespace' |
101+
'typedef';
102+
87103
declare type Comment = {
88104
errors: Array<CommentError>,
89105
tags: Array<CommentTag>,
@@ -106,10 +122,11 @@ declare type Comment = {
106122
members: CommentMembers,
107123

108124
name?: string,
109-
kind?: string,
125+
kind?: Kind,
126+
110127
memberof?: string,
111-
scope?: string,
112-
access?: string,
128+
scope?: Scope,
129+
access?: Access,
113130
alias?: string,
114131

115132
copyright?: string,
@@ -126,6 +143,12 @@ declare type Comment = {
126143

127144
path?: Array<{
128145
name: string,
129-
scope: string
146+
scope: Scope
130147
}>
131148
};
149+
150+
declare type ReducedComment = {
151+
name: string,
152+
kind: ?Kind,
153+
scope?: ?Scope
154+
}

‎default_theme/index._

+12
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,18 @@
5656
<% }) %>
5757
</ul>
5858
<% } %>
59+
<% if (doc.members.inner && doc.members.inner.length) { %>
60+
<ul class='list-reset py1-ul pl1'>
61+
<li class='h5'><span>Inner members</span></li>
62+
<% doc.members.inner.forEach(function(member) { %>
63+
<li><a
64+
href='#<%=member.namespace%>'
65+
class='regular pre-open'>
66+
#<%- member.name %>
67+
</a></li>
68+
<% }) %>
69+
</ul>
70+
<% } %>
5971
<% if (doc.members.events && doc.members.events.length) { %>
6072
<ul class='list-reset py1-ul pl1'>
6173
<li class='h5'>Events</li>

‎lib/hierarchy.js

+33-16
Original file line numberDiff line numberDiff line change
@@ -10,12 +10,18 @@ var hasOwnProperty = Object.prototype.hasOwnProperty;
1010
*/
1111
let isEvent = member => member.kind === 'event';
1212

13-
/*::
14-
declare type ReducedComment = {
15-
name: string,
16-
kind: ?string,
17-
scope?: ?string
18-
} */
13+
/**
14+
* We need to have members of all valid JSDoc scopes.
15+
* @private
16+
*/
17+
let getMembers = () => ({
18+
global: Object.create(null),
19+
inner: Object.create(null),
20+
instance: Object.create(null),
21+
events: Object.create(null),
22+
static: Object.create(null)
23+
});
24+
1925

2026
/**
2127
* Pick only relevant properties from a comment to store them in
@@ -49,12 +55,10 @@ function pick(comment/*: Comment */)/*: ?ReducedComment */ {
4955
module.exports = function (comments/*: Array<Comment>*/) {
5056
var id = 0,
5157
root = {
52-
members: {
53-
instance: Object.create(null),
54-
static: Object.create(null)
55-
}
58+
members: getMembers()
5659
};
5760

61+
5862
comments.forEach(comment => {
5963
var path = [];
6064

@@ -86,10 +90,7 @@ module.exports = function (comments/*: Array<Comment>*/) {
8690
if (!hasOwnProperty.call(node.members[scope], name)) {
8791
node.members[scope][name] = {
8892
comments: [],
89-
members: {
90-
instance: Object.create(null),
91-
static: Object.create(null)
92-
}
93+
members: getMembers()
9394
};
9495
}
9596

@@ -138,7 +139,7 @@ module.exports = function (comments/*: Array<Comment>*/) {
138139
comment.members[scope] = node.members[scope];
139140
}
140141

141-
var events = comment.members.events || [];
142+
var events = comment.members.events;
142143
var groups = [];
143144

144145
if (comment.members.instance.length) {
@@ -155,6 +156,20 @@ module.exports = function (comments/*: Array<Comment>*/) {
155156
comment.members.static = groups[false] || [];
156157
}
157158

159+
if (comment.members.inner.length) {
160+
groups = _.groupBy(comment.members.inner, isEvent);
161+
162+
events = events.concat(groups[true] || []);
163+
comment.members.inner = groups[false] || [];
164+
}
165+
166+
if (comment.members.global.length) {
167+
groups = _.groupBy(comment.members.global, isEvent);
168+
169+
events = events.concat(groups[true] || []);
170+
comment.members.global = groups[false] || [];
171+
}
172+
158173
comment.members.events = events;
159174

160175
comment.path = path.map(pick)
@@ -163,7 +178,9 @@ module.exports = function (comments/*: Array<Comment>*/) {
163178

164179
var scopeChars = {
165180
instance: '#',
166-
static: '.'
181+
static: '.',
182+
inner: '~',
183+
global: ''
167184
};
168185

169186
comment.namespace = comment.path.reduce((memo, part) => {

‎lib/output/markdown_ast.js

+6
Original file line numberDiff line numberDiff line change
@@ -212,12 +212,18 @@ function buildMarkdownAST(comments/*: Array<Comment> */, config/*: Documentation
212212
.concat(throwsSection(comment))
213213
.concat(returnsSection(comment))
214214
.concat(metaSection(comment))
215+
.concat(!!comment.members.global.length &&
216+
comment.members.global.reduce((memo, child) =>
217+
memo.concat(generate(depth + 1, child)), []))
215218
.concat(!!comment.members.instance.length &&
216219
comment.members.instance.reduce((memo, child) =>
217220
memo.concat(generate(depth + 1, child)), []))
218221
.concat(!!comment.members.static.length &&
219222
comment.members.static.reduce((memo, child) =>
220223
memo.concat(generate(depth + 1, child)), []))
224+
.concat(!!comment.members.inner.length &&
225+
comment.members.inner.reduce((memo, child) =>
226+
memo.concat(generate(depth + 1, child)), []))
221227
.filter(Boolean);
222228
}
223229

‎lib/parse.js

+2
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ var flatteners = {
2121
* @returns {undefined} has side-effects
2222
*/
2323
'access': function (result, tag) {
24+
// doctrine ensures that tag.access is valid
2425
result.access = tag.access;
2526
},
2627
'alias': flattenName,
@@ -208,6 +209,7 @@ var flatteners = {
208209
* @returns {undefined} has side-effects
209210
*/
210211
'kind': function (result, tag) {
212+
// doctrine ensures that tag.kind is valid
211213
result.kind = tag.kind;
212214
},
213215
'lends': flattenDescription,

‎lib/serve/error_page.js

+1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
/* @flow */
2+
/* eslint no-console: 0 */
23
'use strict';
34
var File = require('vinyl');
45
var ansiHTML = require('ansi-html');

‎test/fixture/_external-deps-included.json

+12-6
Original file line numberDiff line numberDiff line change
@@ -121,9 +121,11 @@
121121
"name": "foo",
122122
"kind": "function",
123123
"members": {
124+
"global": [],
125+
"inner": [],
124126
"instance": [],
125-
"static": [],
126-
"events": []
127+
"events": [],
128+
"static": []
127129
},
128130
"path": [
129131
{
@@ -291,9 +293,11 @@
291293
"name": "main",
292294
"kind": "function",
293295
"members": {
296+
"global": [],
297+
"inner": [],
294298
"instance": [],
295-
"static": [],
296-
"events": []
299+
"events": [],
300+
"static": []
297301
},
298302
"path": [
299303
{
@@ -461,9 +465,11 @@
461465
"name": "index",
462466
"kind": "function",
463467
"members": {
468+
"global": [],
469+
"inner": [],
464470
"instance": [],
465-
"static": [],
466-
"events": []
471+
"events": [],
472+
"static": []
467473
},
468474
"path": [
469475
{

‎test/fixture/_multi-file-input.json

+8-4
Original file line numberDiff line numberDiff line change
@@ -238,9 +238,11 @@
238238
"name": "returnTwo",
239239
"kind": "function",
240240
"members": {
241+
"global": [],
242+
"inner": [],
241243
"instance": [],
242-
"static": [],
243-
"events": []
244+
"events": [],
245+
"static": []
244246
},
245247
"path": [
246248
{
@@ -408,9 +410,11 @@
408410
"name": "simple.input",
409411
"kind": "function",
410412
"members": {
413+
"global": [],
414+
"inner": [],
411415
"instance": [],
412-
"static": [],
413-
"events": []
416+
"events": [],
417+
"static": []
414418
},
415419
"path": [
416420
{

‎test/fixture/boolean-literal-type.output.json

+4-2
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,11 @@
7272
"name": "f",
7373
"kind": "function",
7474
"members": {
75+
"global": [],
76+
"inner": [],
7577
"instance": [],
76-
"static": [],
77-
"events": []
78+
"events": [],
79+
"static": []
7880
},
7981
"path": [
8082
{

‎test/fixture/class.output.json

+12-6
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,8 @@
167167
"kind": "class",
168168
"name": "MyClass",
169169
"members": {
170+
"global": [],
171+
"inner": [],
170172
"instance": [
171173
{
172174
"description": {
@@ -400,9 +402,11 @@
400402
"memberof": "MyClass",
401403
"scope": "instance",
402404
"members": {
405+
"global": [],
406+
"inner": [],
403407
"instance": [],
404-
"static": [],
405-
"events": []
408+
"events": [],
409+
"static": []
406410
},
407411
"path": [
408412
{
@@ -575,9 +579,11 @@
575579
"memberof": "MyClass",
576580
"scope": "instance",
577581
"members": {
582+
"global": [],
583+
"inner": [],
578584
"instance": [],
579-
"static": [],
580-
"events": []
585+
"events": [],
586+
"static": []
581587
},
582588
"path": [
583589
{
@@ -593,8 +599,8 @@
593599
"namespace": "MyClass#getUndefined"
594600
}
595601
],
596-
"static": [],
597-
"events": []
602+
"events": [],
603+
"static": []
598604
},
599605
"path": [
600606
{

‎test/fixture/document-exported-export-default-object.output.json

+8-4
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,11 @@
3535
"todos": [],
3636
"name": "document-exported-export-default-object.input",
3737
"members": {
38+
"global": [],
39+
"inner": [],
3840
"instance": [],
39-
"static": [],
40-
"events": []
41+
"events": [],
42+
"static": []
4143
},
4244
"path": [
4345
{
@@ -82,9 +84,11 @@
8284
"todos": [],
8385
"name": "x",
8486
"members": {
87+
"global": [],
88+
"inner": [],
8589
"instance": [],
86-
"static": [],
87-
"events": []
90+
"events": [],
91+
"static": []
8892
},
8993
"path": [
9094
{

‎test/fixture/document-exported-export-default-value.output.json

+4-2
Original file line numberDiff line numberDiff line change
@@ -35,9 +35,11 @@
3535
"todos": [],
3636
"name": "document-exported-export-default-value.input",
3737
"members": {
38+
"global": [],
39+
"inner": [],
3840
"instance": [],
39-
"static": [],
40-
"events": []
41+
"events": [],
42+
"static": []
4143
},
4244
"path": [
4345
{

0 commit comments

Comments
 (0)