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

Lines changed: 28 additions & 5 deletions
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._

Lines changed: 12 additions & 0 deletions
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

Lines changed: 33 additions & 16 deletions
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

Lines changed: 6 additions & 0 deletions
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

Lines changed: 2 additions & 0 deletions
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

Lines changed: 1 addition & 0 deletions
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

Lines changed: 12 additions & 6 deletions
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

Lines changed: 8 additions & 4 deletions
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

Lines changed: 4 additions & 2 deletions
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

Lines changed: 12 additions & 6 deletions
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
{

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