Skip to content

Commit 6d274a3

Browse files
pnsticknepnstickne
committed
JSDoc/Docstrap generation
- Made deprecated entries more apparent - A deprecation notice is moved above the description to make it actually obvious - The navigation item is marked (currently with line-through) to visual discourage even thinking about it. - "protected" members are displayed as "internal" - Enforces the idea that using them from outside the core library is possible even though there is no public guarantee - There is also and advice note added to the "Deprecated/Internal" section reminding the users of such. - The "Type" heading is removed when such is trivially visible in the type-signature of the item. - The "Returns" section for methods is moved before the details (So it is displayed about the "Source" and other details.) - The type is better integrated into "Returns"
1 parent 0fc70db commit 6d274a3

8 files changed

Lines changed: 116 additions & 39 deletions

File tree

‎docs/build/docstrap-master/template/publish.js‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -287,7 +287,8 @@ function buildNav( members ) {
287287

288288
nav.class.members.push( {
289289
link: linkto( c.longname, c.name ),
290-
depth: c.longname.split('.').length - 1
290+
depth: c.longname.split('.').length - 1,
291+
member: c
291292
} );
292293
}
293294
seen[c.longname] = true;

‎docs/build/docstrap-master/template/static/scripts/toc.js‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,15 @@ jQuery.fn.toc.defaults = {
201201
return $heading.text();
202202
},
203203
itemClass: function(i, heading, $heading, prefix) {
204-
return prefix + '-' + $heading[0].tagName.toLowerCase();
204+
// Remove all classes not starting like 'toc-'
205+
var tocClasses = ($heading.attr('class') || '')
206+
.replace(/\b\S+/gi, function (m) {
207+
return m.indexOf("toc-") === 0 ? m : '';
208+
});
209+
210+
var itemClass = prefix + '-' + $heading[0].tagName.toLowerCase();
211+
212+
return tocClasses + ' ' + itemClass;
205213
}
206214

207215
};

‎docs/build/docstrap-master/template/static/styles/default.css‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
/**
2+
Default styles for some custom classes.
3+
Change with theme as appropriate..
4+
*/
5+
6+
.deprecated-notice {
7+
padding: 10px;
8+
}
9+
10+
.toc-deprecated {
11+
text-decoration: line-through;
12+
}
13+
14+
.returns-type {
15+
float: left;
16+
padding-right: 10px;
17+
}
18+
19+
.returns-desc {
20+
}

‎docs/build/docstrap-master/template/tmpl/details.tmpl‎

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11
<?js
22
var data = obj;
33
var self = this;
4+
function isInternal (data) {
5+
return data.access === 'protected' || data.access === 'private';
6+
}
7+
function deprecatedHeading (data) {
8+
if (data.deprecated && isInternal(data)) {
9+
return "Deprecated / Internal";
10+
} else if (isInternal(data)) {
11+
return "Internal"
12+
} else {
13+
return "Deprecated"
14+
}
15+
}
416
?>
517
<dl class="details">
618
<?js
@@ -31,11 +43,14 @@ var self = this;
3143
</li></dd>
3244
<?js } ?>
3345

34-
<?js if (data.deprecated) { ?>
35-
<dt class="important tag-deprecated">Deprecated:</dt><?js
36-
if (data.deprecated === true) { ?><dd class="yes-def tag-deprecated"><ul class="dummy"><li>Yes</li></ul></dd><?js }
37-
else { ?><dd><ul class="dummy"><li><?js= data.deprecated ?></li><ul></dd><?js }
38-
?>
46+
<?js if (data.deprecated || isInternal(data)) { ?>
47+
<dt class="important tag-deprecated"><?js= deprecatedHeading(data) ?>:</dt>
48+
<dd class="tag-deprecated"><ul>
49+
<?js if (data.access === 'protected') { ?>
50+
<li>This member is <em>internal (protected)</em> and may be modified or removed in the future.</li><?js } ?>
51+
<?js if (data.deprecated != null) { ?>
52+
<li><?js if (isInternal(data)) { ?><em>Deprecated:</em> <?js }?><?js= data.deprecated === true ? 'Yes' : data.deprecated ?></li><?js } ?>
53+
</ul></dd>
3954
<?js } ?>
4055

4156
<?js if (data.author && author.length) {?>

‎docs/build/docstrap-master/template/tmpl/layout.tmpl‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,9 @@
88
<!--[if lt IE 9]>
99
<script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
1010
<![endif]-->
11+
12+
<link type="text/css" rel="stylesheet" href="styles/default.css">
13+
1114
<link type="text/css" rel="stylesheet" href="styles/sunlight.default.css">
1215

1316
<?js if (this.navOptions.theme === "darkstrap"){ ?>

‎docs/build/docstrap-master/template/tmpl/members.tmpl‎

Lines changed: 27 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,47 @@
11
<?js
22
var data = obj;
33
var self = this;
4+
function mkSignature () {
5+
var attribs = data.attribs;
6+
attribs = attribs.replace('protected', 'internal');
7+
8+
return (attribs + data.name +
9+
(data.signature ? data.signature : ''));
10+
}
11+
function hasComplexType (data) {
12+
var names = data.type ? data.type.names : [];
13+
if (!names.length) {
14+
return false;
15+
} else if (names.length > 1) {
16+
return true;
17+
} else {
18+
// Simple is word-characters + {# . ~}
19+
return !names[0].match(/^[\w\x23.~]*$/);
20+
}
21+
}
422
?>
523
<dt>
6-
<h4 class="name" id="<?js= id ?>"><?js= data.attribs + name + (data.signature ? data.signature : '') ?></h4>
24+
<h4 class="name <?js= data.deprecated ? 'toc-deprecated' : ''?>"
25+
id="<?js= id ?>"><?js= mkSignature(data) ?></h4>
726

827
<?js if (data.summary) { ?>
928
<p class="summary"><?js= summary ?></p>
1029
<?js } ?>
1130
</dt>
1231
<dd>
32+
<?js if (data.deprecated) { ?>
33+
<dt class="important deprecated-notice">
34+
This method is <em>deprecated</em> and should not be used. It may be removed in the future.
35+
</dt>
36+
<?js } ?>
37+
1338
<?js if (data.description) { ?>
1439
<div class="description">
1540
<?js= data.description ?>
1641
</div>
1742
<?js } ?>
1843

19-
<?js if (data.type && data.type.names) {?>
44+
<?js if (hasComplexType(data)) {?>
2045
<h5>Type:</h5>
2146
<ul>
2247
<li>

‎docs/build/docstrap-master/template/tmpl/method.tmpl‎

Lines changed: 26 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,30 @@
11
<?js
22
var data = obj;
33
var self = this;
4+
function mkSignature (data) {
5+
var attribs = data.attribs;
6+
attribs = attribs.replace('protected', 'internal');
7+
8+
return (attribs + (data.kind === 'class' ? 'new ' : '') +
9+
data.name +
10+
(data.kind !== 'event' ? data.signature : ''));
11+
}
412
?>
513
<dt>
6-
<h4 class="name" id="<?js= id ?>"><?js= data.attribs + (kind === 'class' ? 'new ' : '') + name + (kind !== 'event' ? data.signature : '') ?></h4>
14+
<h4 class="name <?js= data.deprecated ? 'toc-deprecated' : ''?>"
15+
id="<?js= id ?>"><?js= mkSignature(data) ?></h4>
716

817
<?js if (data.summary) { ?>
918
<p class="summary"><?js= summary ?></p>
1019
<?js } ?>
1120
</dt>
1221
<dd>
13-
22+
<?js if (data.deprecated) { ?>
23+
<dt class="important deprecated-notice">
24+
This method is <em>deprecated</em> and should not be used. It may be removed in the future.
25+
</dt>
26+
<?js } ?>
27+
1428
<?js if (data.description) { ?>
1529
<div class="description">
1630
<?js= data.description ?>
@@ -35,6 +49,15 @@ var self = this;
3549
<h5>Parameters:</h5>
3650
<?js= this.partial('params.tmpl', params) ?>
3751
<?js } ?>
52+
53+
<?js if (data.returns && returns.length) { ?>
54+
<h5>Returns:</h5>
55+
<div class="returns">
56+
<?js returns.forEach(function(r) { ?>
57+
<?js= self.partial('returns.tmpl', r) ?>
58+
<?js }); ?>
59+
</div>
60+
<?js } ?>
3861

3962
<?js= this.partial('details.tmpl', data) ?>
4063

@@ -69,19 +92,7 @@ var self = this;
6992
exceptions.forEach(function(r) { ?>
7093
<?js= self.partial('exceptions.tmpl', r) ?>
7194
<?js });
72-
} } ?>
73-
74-
<?js if (data.returns && returns.length) { ?>
75-
<h5>Returns:</h5>
76-
<?js if (returns.length > 1) { ?><ul><?js
77-
returns.forEach(function(r) { ?>
78-
<li><?js= self.partial('returns.tmpl', r) ?></li>
79-
<?js });
80-
?></ul><?js } else {
81-
returns.forEach(function(r) { ?>
82-
<?js= self.partial('returns.tmpl', r) ?>
83-
<?js });
84-
} } ?>
95+
} } ?>
8596

8697
<?js if (data.examples && examples.length) { ?>
8798
<h5>Example<?js= examples.length > 1? 's':'' ?></h5>

‎docs/build/docstrap-master/template/tmpl/returns.tmpl‎

Lines changed: 9 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,13 @@
11
<?js
22
var data = obj;
3-
if (data.description) {
3+
if (data.description || (data.type && data.type.names)) {
44
?>
5-
<div class="param-desc">
6-
<?js= description ?>
7-
</div>
8-
<?js } ?>
9-
10-
<?js if (data.type && data.type.names) {?>
11-
<dl>
12-
<dt>
13-
Type
14-
</dt>
15-
<dd>
16-
<?js= this.partial('type.tmpl', data.type.names) ?>
17-
</dd>
18-
</dl>
5+
<?js if (data.type && data.type.names) { ?>
6+
<div class="returns-type">
7+
<?js= this.partial('type.tmpl', data.type.names) ?> -
8+
</div>
9+
<?js } ?>
10+
<div class="returns-desc param-desc">
11+
<?js= data.description ?>
12+
</div>
1913
<?js } ?>

0 commit comments

Comments
 (0)