Skip to content

Commit 2405049

Browse files
committed
Update documentation for /tags
1 parent 538521c commit 2405049

File tree

9 files changed

+222
-218
lines changed

9 files changed

+222
-218
lines changed

tags/codeend.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @hide
33
* @parent bit-docs-js/tags
4-
* @module {bit-docs-js/tag} bit-docs-js/tags/codeend @codeend
4+
* @module {bit-docs/types/tag} bit-docs-js/tags/codeend @codeend
55
*
66
* @description
77
*

tags/codestart.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/**
22
* @hide
33
* @parent bit-docs-js/tags
4-
* @module {bit-docs-js/tag} bit-docs-js/tags/codestart @codestart
4+
* @module {bit-docs/types/tag} bit-docs-js/tags/codestart @codestart
55
*
66
* Starts a code block.
77
*

tags/function.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ namedFunction = /\s*function\s+([\w\.\$]+)\s*(~)?\(([^\)]*)/;
99

1010
/**
1111
* @parent bit-docs-js/tags
12-
* @module {bit-docs-js/tag} bit-docs-js/tags/function @function
12+
* @module {bit-docs/types/tag} bit-docs-js/tags/function @function
1313
*
1414
* @description Specifies the comment block is for a function. Use
1515
* [bit-docs-js/tags/param] to specify the parameters of a function.

tags/option.js

Lines changed: 128 additions & 126 deletions
Original file line numberDiff line numberDiff line change
@@ -2,54 +2,54 @@ var tnd = require("bit-docs-type-annotate").typeNameDescription;
22

33
// go through the types and get the first one that has options
44
var getOptions = function (param) {
5-
if (!param.types) {
6-
return;
7-
}
8-
for (var i = 0; i < param.types.length; i++) {
9-
if (param.types[i].options) {
10-
return param.types[i].options;
11-
}
12-
}
5+
if (!param.types) {
6+
return;
7+
}
8+
for (var i = 0; i < param.types.length; i++) {
9+
if (param.types[i].options) {
10+
return param.types[i].options;
11+
}
12+
}
1313
};
1414

1515
// go through the types and return the first one that has params
1616
var getParams = function (param) {
17-
if (!param.types) {
18-
return;
19-
}
20-
for (var i = 0; i < param.types.length; i++) {
21-
if (param.types[i].params) {
22-
return param.types[i].params;
23-
}
24-
}
17+
if (!param.types) {
18+
return;
19+
}
20+
for (var i = 0; i < param.types.length; i++) {
21+
if (param.types[i].params) {
22+
return param.types[i].params;
23+
}
24+
}
2525
};
2626

2727
// find matching type
2828
var getType = function (types, type) {
29-
for (var i = 0; i < types.length; i++) {
30-
if (types[i].type === type) {
31-
return types[i];
32-
}
33-
}
29+
for (var i = 0; i < types.length; i++) {
30+
if (types[i].type === type) {
31+
return types[i];
32+
}
33+
}
3434
};
3535

3636
var getOrMakeOptionByName = function (options, name) {
37-
for (var i = 0; i < options.length; i++) {
38-
if (options[i].name === name) {
39-
return options[i];
40-
}
41-
}
42-
var option = { name: name };
43-
options.push(option);
44-
return option;
37+
for (var i = 0; i < options.length; i++) {
38+
if (options[i].name === name) {
39+
return options[i];
40+
}
41+
}
42+
var option = { name: name };
43+
options.push(option);
44+
return option;
4545
};
4646

4747
var setOptionData = function (option, data) {
48-
option.description = data.description;
48+
option.description = data.description;
4949

50-
for (var prop in data) {
51-
option[prop] = data[prop];
52-
}
50+
for (var prop in data) {
51+
option[prop] = data[prop];
52+
}
5353
};
5454

5555
/**
@@ -82,7 +82,7 @@ var setOptionData = function (option, data) {
8282
* };
8383
* @codeend
8484
*
85-
* @param {bit-docs/typeExpression} [TYPE] A [bit-docs/typeExpression type expression]. Examples:
85+
* @param {bit-docs-type-annotate/types/typeExpression} [TYPE] A [bit-docs-type-annotate/types/typeExpression type expression]. Examples:
8686
*
8787
* `{String}` - type is a `String`.
8888
* `{function(name)}` - type is a `function` that takes one `name` argument.
@@ -103,7 +103,7 @@ var setOptionData = function (option, data) {
103103
* However, omitting TYPE might confuse your team members, so we recommend
104104
* being explicit and always specifying TYPE for `@option`.
105105
*
106-
* @param {bit-docs/nameExpression} NAME A [bit-docs/nameExpression name expression]. Examples:
106+
* @param {bit-docs-type-annotate/types/nameExpression} NAME A [bit-docs-type-annotate/types/nameExpression name expression]. Examples:
107107
*
108108
* `age` - age is item.
109109
* `[age]` - age is item, age is optional.
@@ -135,45 +135,47 @@ var setOptionData = function (option, data) {
135135
*
136136
* @codestart javascript
137137
* {
138-
* "type": "function",
138+
* "description": "A function named bar.\n",
139139
* "name": "foo.bar",
140140
* "params": [
141141
* {
142+
* "description": "A parameter object with options:",
143+
* "name": "params",
142144
* "types": [
143145
* {
144-
* "type": "Object",
145146
* "options": [
146147
* {
147-
* "name": "aString",
148148
* "description": "An arbitrary string.",
149+
* "name": "aString",
149150
* "types": [
150151
* {
151152
* "type": "String"
152153
* }
153154
* ]
154155
* },
155156
* {
156-
* "name": "oNumber",
157157
* "description": "An optional number.\n",
158+
* "name": "oNumber",
159+
* "optional": true,
158160
* "types": [
159161
* {
160162
* "type": "Number"
161163
* }
162-
* ],
163-
* "optional": true
164+
* ]
164165
* }
165-
* ]
166+
* ],
167+
* "type": "Object"
166168
* }
167-
* ],
168-
* "name": "params",
169-
* "description": "A parameter object with options:"
169+
* ]
170170
* }
171171
* ],
172172
* "parent": "foo",
173-
* "description": "A function named bar.\n"
173+
* "type": "function"
174174
* }
175175
* @codeend
176176
*
177+
* @highlight 7-32,only
178+
*
177179
* That [bit-docs/types/docObject] an be used in a template like this:
178180
*
179181
* @codestart html
@@ -194,100 +196,100 @@ var setOptionData = function (option, data) {
194196
* {{/if}}
195197
* @codeend
196198
*
197-
* See [signature.mustache] for a more complex template that uses the
198-
* [bit-docs/types/docObject] resulting from `@option`.
199+
* See [bit-docs-js/templates/signature.mustache] for a more complex template
200+
* that uses the [bit-docs/types/docObject] resulting from `@option`.
199201
*/
200202
module.exports = {
201-
addMore: function (line, last) {
202-
if (last) last.description += "\n" + line;
203-
},
204-
add: function (line, tagData) {
205-
var noNameData = tnd(line, true),
206-
data = tnd(line),
207-
i,
208-
option,
209-
obj;
203+
addMore: function (line, last) {
204+
if (last) last.description += "\n" + line;
205+
},
206+
add: function (line, tagData) {
207+
var noNameData = tnd(line, true),
208+
data = tnd(line),
209+
i,
210+
option,
211+
obj;
210212

211-
if (tagData && this !== tagData) {
212-
var options = getOptions(tagData);
213+
if (tagData && this !== tagData) {
214+
var options = getOptions(tagData);
213215

214-
if (options) {
215-
option = getOrMakeOptionByName(options, data.name);
216-
setOptionData(option, data);
217-
return option;
218-
}
219-
}
216+
if (options) {
217+
option = getOrMakeOptionByName(options, data.name);
218+
setOptionData(option, data);
219+
return option;
220+
}
221+
}
220222

221-
// start processing
222-
if (this.type == "typedef" || this.type === "module") {
223-
// Typedefs can have option values, but those values can be objects
224-
// with options.
225-
// So, we should check in options objects first
226-
for (i = 0; i < this.types.length; i++) {
227-
obj = this.types[i];
228-
if (obj.type == "Object") {
229-
option = getOrMakeOptionByName(obj.options || [], data.name);
230-
if (option) {
231-
setOptionData(option, data);
232-
return option;
233-
}
234-
}
235-
}
236-
}
223+
// start processing
224+
if (this.type == "typedef" || this.type === "module") {
225+
// Typedefs can have option values, but those values can be objects
226+
// with options.
227+
// So, we should check in options objects first
228+
for (i = 0; i < this.types.length; i++) {
229+
obj = this.types[i];
230+
if (obj.type == "Object") {
231+
option = getOrMakeOptionByName(obj.options || [], data.name);
232+
if (option) {
233+
setOptionData(option, data);
234+
return option;
235+
}
236+
}
237+
}
238+
}
237239

238-
// we should look to find something matching
239-
var locations = [this._curReturn, this._curParam, (this.params && this.params[this.params.length - 1]), this];
240+
// we should look to find something matching
241+
var locations = [this._curReturn, this._curParam, (this.params && this.params[this.params.length - 1]), this];
240242

241-
// only process this type of option if there is one value
242-
if (noNameData.types && noNameData.types.length == 1) {
243-
var typeData = noNameData.types[0];
244-
for (i = 0; i < locations.length; i++) {
245-
obj = locations[i];
246-
if (obj) {
247-
if (!obj.types) {
248-
obj.types = [];
249-
}
250-
var type = getType(obj.types, typeData.type);
251-
if (type) {
252-
// copy description
253-
type.description = noNameData.description;
243+
// only process this type of option if there is one value
244+
if (noNameData.types && noNameData.types.length == 1) {
245+
var typeData = noNameData.types[0];
246+
for (i = 0; i < locations.length; i++) {
247+
obj = locations[i];
248+
if (obj) {
249+
if (!obj.types) {
250+
obj.types = [];
251+
}
252+
var type = getType(obj.types, typeData.type);
253+
if (type) {
254+
// copy description
255+
type.description = noNameData.description;
254256

255-
// copy any additional type info
256-
for (var prop in typeData) {
257-
type[prop] = typeData[prop];
258-
}
257+
// copy any additional type info
258+
for (var prop in typeData) {
259+
type[prop] = typeData[prop];
260+
}
259261

260-
return type;
261-
}
262-
}
263-
}
264-
}
262+
return type;
263+
}
264+
}
265+
}
266+
}
265267

266-
var prevParam = this._curReturn || this._curParam || (this.params && this.params[this.params.length - 1]) || this;
268+
var prevParam = this._curReturn || this._curParam || (this.params && this.params[this.params.length - 1]) || this;
267269

268-
if (!data.name) {
269-
console.log("LINE: \n" + line + "\n does not match @option [{TYPE}] NAME DESCRIPTION");
270-
}
270+
if (!data.name) {
271+
console.log("LINE: \n" + line + "\n does not match @option [{TYPE}] NAME DESCRIPTION");
272+
}
271273

272-
// try to get a params or options object
273-
var params = getParams(prevParam),
274-
options = getOptions(prevParam);
274+
// try to get a params or options object
275+
var params = getParams(prevParam),
276+
options = getOptions(prevParam);
275277

276-
if (!options && !params) {
277-
if (prevParam.types[0]) {
278-
options = (prevParam.types[0].options = []);
279-
} else {
280-
console.log("LINE: \n" + line + "\n could not find an object or arguments to add options to.");
281-
return;
282-
}
283-
}
278+
if (!options && !params) {
279+
if (prevParam.types[0]) {
280+
options = (prevParam.types[0].options = []);
281+
} else {
282+
console.log("LINE: \n" + line + "\n could not find an object or arguments to add options to.");
283+
return;
284+
}
285+
}
284286

285-
// get the named one
286-
option = getOrMakeOptionByName(options || params, data.name);
287+
// get the named one
288+
option = getOrMakeOptionByName(options || params, data.name);
287289

288-
// add to it
289-
setOptionData(option, data);
290+
// add to it
291+
setOptionData(option, data);
290292

291-
return option;
292-
}
293+
return option;
294+
}
293295
};

0 commit comments

Comments
 (0)