Skip to content

Commit 7d0dc68

Browse files
photonstormphotonstorm
committed
Merge pull request phaserjs#1308 from pnstickne/wip-jsdoc-format
JSDoc template updates - cleanup and some changes
2 parents a4e049a + 4ba8fe1 commit 7d0dc68

7 files changed

Lines changed: 126 additions & 42 deletions

File tree

‎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: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
/**
2+
Default styles for some custom classes.
3+
Change with theme as appropriate..
4+
*/
5+
6+
.deprecated-notice {
7+
border: 2px solid rgb(255, 238, 238);
8+
padding: 10px;
9+
margin-bottom: 10px;
10+
}
11+
12+
.toc-deprecated {
13+
text-decoration: line-through;
14+
}
15+
16+
.returns-type {
17+
float: left;
18+
padding-right: 10px;
19+
}
20+
21+
.returns-desc {
22+
}
23+
24+
dt a {
25+
font-weight: normal;
26+
}

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

Lines changed: 26 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
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+
}
16+
function cleanShortPath (shortpath) {
17+
return shortpath.replace(/^.*\bsrc[/]/, '');
18+
}
419
?>
520
<dl class="details">
621
<?js
@@ -31,11 +46,14 @@ var self = this;
3146
</li></dd>
3247
<?js } ?>
3348

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-
?>
49+
<?js if (data.deprecated || isInternal(data)) { ?>
50+
<dt class="important tag-deprecated"><?js= deprecatedHeading(data) ?>:</dt>
51+
<dd class="tag-deprecated"><ul>
52+
<?js if (data.access === 'protected') { ?>
53+
<li>This member is <em>internal (protected)</em> and may be modified or removed in the future.</li><?js } ?>
54+
<?js if (data.deprecated != null) { ?>
55+
<li><?js if (isInternal(data)) { ?><em>Deprecated:</em> <?js }?><?js= data.deprecated === true ? 'Yes' : data.deprecated ?></li><?js } ?>
56+
</ul></dd>
3957
<?js } ?>
4058

4159
<?js if (data.author && author.length) {?>
@@ -63,10 +81,9 @@ var self = this;
6381
<?js } ?>
6482

6583
<?js if (data.meta) {?>
66-
<dt class="tag-source">Source:</dt>
67-
<dd class="tag-source"><ul class="dummy"><li>
68-
<?js= self.linkto(meta.shortpath) ?><?js if (this.navOptions.linenums) {?>, <?js= self.linkto(meta.shortpath, 'line ' + meta.lineno, null, 'sunlight-1-line-' + meta.lineno) ?><?js } ?>
69-
</li></ul></dd>
84+
<dt class="tag-source">Source -
85+
<?js= self.linkto(meta.shortpath, cleanShortPath(meta.shortpath)) ?><?js if (this.navOptions.linenums) {?>, <?js= self.linkto(meta.shortpath, 'line ' + meta.lineno, null, 'sunlight-1-line-' + meta.lineno) ?><?js } ?>
86+
</dt>
7087
<?js } ?>
7188

7289
<?js if (data.tutorials && tutorials.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)