Skip to content

Commit bad42ab

Browse files
justinbmeyerjustinbmeyer
authored
Merge pull request #10 from bit-docs/signature-template
Add basics for signature template
2 parents 7d00b1f + 3dc08cf commit bad42ab

File tree

5 files changed

+224
-99
lines changed

5 files changed

+224
-99
lines changed

‎bit-docs.js‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,16 @@ var path = require("path");
5353
* HTML for the tags added by this plugin.
5454
*/
5555
module.exports = function(bitDocs){
56+
var pkg = require("./package.json");
57+
var dependencies = {};
58+
dependencies[pkg.name] = pkg.version;
59+
5660
// register your tags
5761
bitDocs.register("tags", tags);
5862
bitDocs.register("processor", processJavaScript);
5963

6064
bitDocs.register("html", {
61-
templates: path.join(__dirname, "templates")
65+
templates: path.join(__dirname, "templates"),
66+
dependencies: dependencies
6267
});
6368
};

‎index.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* @parent bit-docs-js/static
3+
* @module bit-docs-js/index.js
4+
*
5+
* Main front end JavaScript file for static portion of this plugin.
6+
*
7+
* Simply requires [bit-docs-js/static/styles/signature.less].
8+
*/
9+
require('./static/styles/signature.less');

‎static/styles/signature.less‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
@import "locate://bit-docs-site/styles/variables.less";
2+
3+
/**
4+
* @parent bit-docs-js/static
5+
* @module bit-docs-js/static/styles/signature.less
6+
*
7+
* @description Base styles for signature tag.
8+
*
9+
* @body
10+
*
11+
* Keep spacing consistent for signature options and/or parameters when the
12+
* description text ends in a paragraph that has a bottom margin, or ends in
13+
* another element without a default bottom margin (such as an HTML list).
14+
*
15+
* Uses `>` selectors to scope only those `<ul>`/`<ol>` added by the template.
16+
*
17+
* Paragraphs have a default bottom margin of 1em, so this collapses with that.
18+
*/
19+
.signature {
20+
.options, .parameters {
21+
&>*>li {
22+
margin-bottom: 1em;
23+
}
24+
}
25+
}

‎templates/helpers.js‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
var escapeHTML = require("escape-html");
2+
3+
module.exports = function (docMap, options, getCurrent, helpers, OtherHandlebars) {
4+
var docMapInfo = new DocMapInfo(docMap, getCurrent);
5+
6+
return {
7+
"makeSignature": function (code) {
8+
if (code) {
9+
return escapeHTML(code);
10+
}
11+
12+
var sig = "";
13+
if (this.type === "module") {
14+
sig = "__" + this.name + "__ ";
15+
}
16+
if (this.types) {
17+
return sig + helpers.makeTypes(this.types);
18+
}
19+
20+
if (! /function|constructor/i.test(this.type) && !this.params && !this.returns) {
21+
return sig + helpers.makeType(this);
22+
}
23+
24+
// if it's a constructor add new
25+
if (this.type === "constructor") {
26+
sig += "new ";
27+
}
28+
29+
// get the name part right
30+
var parent = docMap[this.parent];
31+
if (parent) {
32+
if (parent.type == "prototype") {
33+
var parentParent = docMap[parent.parent];
34+
sig += (parentParent.alias || (lastPartOfName(parentParent.name) + ".")).toLowerCase();
35+
36+
} else {
37+
sig += (parent.alias || lastPartOfName(parent.name) + ".");
38+
}
39+
40+
sig += (lastPartOfName(this.name) || "function");
41+
} else {
42+
sig += "function";
43+
}
44+
45+
sig += "(" + helpers.makeParamsString(this.params) + ")";
46+
47+
return sig;
48+
},
49+
"makeParams": function () {
50+
var result = "<b>" + this.name + "</b>";
51+
if (this.types) {
52+
result += " <code>" + helpers.makeTypesString(this.types) + "</code>";
53+
}
54+
return result;
55+
},
56+
makeReturn: function () {
57+
if (this.types) {
58+
return " <code>" + helpers.makeTypesString(this.types) + "</code>";
59+
}
60+
},
61+
makeTypesString: function (types) {
62+
if (types && types.length) {
63+
var txt = "{" + helpers.makeTypes(types);
64+
return txt + "}";
65+
} else {
66+
return '';
67+
}
68+
},
69+
makeTypes: function (types) {
70+
if (types.length) {
71+
// turns [{type: 'Object'}, {type: 'String'}] into '{Object | String}'
72+
return types.map(helpers.makeType).join('|');
73+
} else {
74+
return '';
75+
}
76+
},
77+
makeType: function (t) {
78+
if (t.type === "function") {
79+
var fn = t.params && t.params.length ?
80+
"(" + helpers.makeParamsString(t.params) + ")" : "";
81+
82+
if (t.constructs && t.constructs.types) {
83+
fn = "constructor" + fn;
84+
fn += " => " + helpers.makeTypes(t.constructs.types);
85+
} else {
86+
fn = "function" + fn;
87+
}
88+
89+
return fn;
90+
}
91+
92+
var type = docMap[t.type];
93+
var title = type && type.title || undefined;
94+
var txt = helpers.linkTo(t.type, title);
95+
var params;
96+
97+
if (t.template && t.template.length) {
98+
txt += "&lt;" + t.template.map(function (templateItem) {
99+
return helpers.makeTypes(templateItem.types);
100+
}).join(",") + "&gt;";
101+
}
102+
103+
if (type) {
104+
if (type.type === "function" && (type.params || type.signatures)) {
105+
params = type.params || (type.signatures[0] && type.signatures[0].params) || [];
106+
} else if (type.type === "typedef" && type.types && type.types[0] && type.types[0].type == "function") {
107+
params = type.types[0].params;
108+
}
109+
if (params) {
110+
txt += "(" + helpers.makeParamsString(params) + ")";
111+
}
112+
}
113+
114+
return txt;
115+
},
116+
makeParamsString: function (params) {
117+
if (!params || !params.length) {
118+
return "";
119+
}
120+
121+
return params.map(function (param) {
122+
// try to look up the title
123+
var type = param.types && param.types[0] && param.types[0].type;
124+
return helpers.linkTo(type, param.name) +
125+
(param.variable ? "..." : "");
126+
}).join(", ");
127+
},
128+
};
129+
};
130+
131+
var DocMapInfo = function (docMap, getCurrent) {
132+
this.docMap = docMap;
133+
this.getCurrent = getCurrent;
134+
};

‎templates/signature.mustache‎

Lines changed: 50 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -1,103 +1,55 @@
1-
<h2 id="{{makeSignatureId code params returns context}}">{{{makeSignature code}}}
2-
{{#if release}}<span class="pull-right release">{{release}}</span>{{/if}}</h2>
3-
<div class="signature-wrapper">
4-
{{{chain "makeHtml" "makeLinks" description}}}
5-
{{#if params}}
6-
<h3>Parameters</h3>
1+
<div class="signature">
2+
<h2 class="signature-title">
3+
<code>{{{makeSignature code}}}</code>
4+
</h2>
75

8-
<ol class="parameters">
9-
{{#params}}
10-
<li class="parameter">
11-
<h4>{{name}}{{#if defaultValue}}<code>={{defaultValue}}</code>{{/if}}
12-
{{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}{{#if optional}}<span class="pull-right optional">Optional{{#if variable}} Variable{{/if}}</span>{{/if}}</h4>
13-
<div class="description">
14-
{{{chain "makeHtml" "makeLinks" description}}}
15-
</div>
16-
{{#types}}
17-
{{#if options.length}}
18-
<ul class="options">
19-
{{#options}}
20-
<li class="option">
21-
<h5>{{name}}
22-
{{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}
23-
</h5>
24-
<div class="description">
25-
{{{chain "makeHtml" "makeLinks" description}}}
26-
</div>
27-
</li>
28-
{{/options}}
29-
</ul>
30-
{{/if}}
31-
{{/types}}
32-
</li>
33-
{{/params}}
34-
</ol>
35-
{{/if}}
36-
{{#if returns}}
37-
<h3>Returns</h3>
38-
<div class="returns">
39-
<h4><code>{{{makeTypesString returns.types}}}</code></h4>
40-
<div class="description">
41-
{{{chain "makeHtml" "makeLinks" returns.description}}}
42-
</div>
6+
{{{makeHtml (makeLinks description)}}}
437

44-
{{#getTypesWithDescriptions returns.types}}
45-
<ul class="options">
46-
{{#types}}
47-
<li class="option">
48-
<h5>{{name}}
49-
{{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}
50-
</h5>
51-
<div class="description">
52-
{{{chain "makeHtml" "makeLinks" description}}}
53-
</div>
54-
</li>
55-
{{/types}}
56-
</ul>
57-
{{/getTypesWithDescriptions}}
58-
</div>
8+
{{#if params}}
9+
<div class="parameters">
10+
<h3 class="parameters-title">Parameters</h3>
11+
<ol>
12+
{{#params}}
13+
<li>{{{makeParams}}}: {{{makeHtml (makeLinks description)}}}</li>
14+
{{#types}}
15+
{{#if options.length}}
16+
<ul class="options">
17+
{{#options}}
18+
<li class="option">
19+
<h5>{{name}}
20+
{{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}
21+
</h5>
22+
<div class="description">
23+
{{{chain "makeHtml" "makeLinks" description}}}
24+
</div>
25+
</li>
26+
{{/options}}
27+
</ul>
28+
{{/if}}
29+
{{/types}}
30+
{{/params}}
31+
</ol>
32+
</div>
33+
{{/if}}
5934

60-
{{/if}}
61-
{{#if context}}
62-
<h3>This</h3>
63-
<div class="returns">
64-
<h4><code>{{{makeTypesString context.types}}}</code></h4>
65-
<div class="description">
66-
{{{chain "makeHtml" "makeLinks" context.description}}}
67-
</div>
68-
</div>
69-
{{/if}}
70-
71-
{{#if options.length}}
72-
<h3>Properties</h3>
73-
74-
<ol class="parameters">
75-
{{#options}}
76-
<li class="parameter">
77-
<h4>{{name}}{{#if defaultValue}}<code>={{defaultValue}}</code>{{/if}}
78-
{{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}{{#if optional}}<span class="pull-right optional">Optional</span>{{/if}}</h4>
79-
<div class="description">
80-
{{{chain "makeHtml" "makeLinks" description}}}
81-
</div>
82-
{{#types}}
83-
{{#if params.length}}
84-
<ul class="options">
85-
{{#params}}
86-
<li class="option">
87-
<h5>{{name}}
88-
{{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}
89-
</h5>
90-
<div class="description">
91-
{{{chain "makeHtml" "makeLinks" description}}}
92-
</div>
93-
</li>
94-
{{/params}}
95-
</ul>
96-
{{/if}}
97-
{{/types}}
98-
</li>
99-
{{/options}}
100-
</ol>
101-
{{/if}}
35+
{{#returns}}
36+
<div class="returns">
37+
<h3 class="returns-title">Returns</h3>
38+
{{{makeReturn}}}: {{{makeHtml (makeLinks description)}}}
39+
</div>
40+
{{/returns}}
10241

42+
{{#if options.length}}
43+
<div class="options">
44+
<h3 class="options-title">Options</h3>
45+
<ul>
46+
{{#options}}
47+
<li>
48+
<b>{{name}}</b> {{#if types}}<code>{{{makeTypesString types}}}</code>{{/if}}:
49+
{{{makeHtml (makeLinks description)}}}
50+
</li>
51+
{{/options}}
52+
</ul>
53+
</div>
54+
{{/if}}
10355
</div>

0 commit comments

Comments
 (0)