Skip to content

Commit 6490c53

Browse files
leoj3nleoj3n
committed
Document the tags
1 parent bf4d1ed commit 6490c53

File tree

7 files changed

+233
-248
lines changed

7 files changed

+233
-248
lines changed

‎bit-docs.js

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
/**
2-
* @module {function} bit-docs-process-tags
32
* @parent plugins
3+
* @module {function} bit-docs-process-tags
4+
* @group bit-docs-process-tags/tags tags
45
*
56
* @description Processes tags for a docMap.
67
*

‎tags/_default.js

Lines changed: 93 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,106 @@
1-
var tnd = require("bit-docs-type-annotate").typeNameDescription,
2-
matchTag = /^\s*@(\w+)/,
3-
distance = require("../lib/distance"),
4-
_ = require('lodash');
1+
var tnd = require("bit-docs-type-annotate").typeNameDescription;
2+
var matchTag = /^\s*@(\w+)/;
3+
var distance = require("../lib/distance");
4+
var _ = require('lodash');
55

6+
/**
7+
* @hide
8+
* @parent bit-docs-process-tags/tags
9+
* @module {bit-docs-js/tag} bit-docs-process-tags/tags/_default @_default
10+
*
11+
* The default tag behavior when `@TAG` begins a line, but no tag is defined
12+
* for `TAG`.
13+
*
14+
* @signature `@TAG NAME[, ...]`
15+
*
16+
* Sets a `TAG` property on the docObject to `"NAME"`.
17+
*
18+
* Example:
19+
* @codestart javascript
20+
* /**
21+
* * @@memberOf _
22+
* *|
23+
* findById: function( id, success ) {
24+
* @codeend
25+
*
26+
* This will make the docObject look like:
27+
*
28+
* ```
29+
* {memberof: "_"}
30+
* ```
31+
*
32+
* If `NAME` values are separated by comma-space (`, `), the values will be set
33+
* as an array. Example:
34+
*
35+
* @codestart javascript
36+
* /**
37+
* * @@memberOf _, lodash
38+
* *|
39+
* findById: function( id, success ) {
40+
* @codeend
41+
*
42+
* This will make the docObject look like:
43+
*
44+
* ```
45+
* {memberof: ["_", "lodash"]}
46+
* ```
47+
*
48+
* If multiple `@TAG NAME`s are found with the same `TAG`, an array with each
49+
* `"NAME"` will be created. Example:
50+
*
51+
* @codestart javascript
52+
* /**
53+
* * @@memberOf _
54+
* * @@memberOf lodash
55+
* *|
56+
* findById: function( id, success ) {
57+
* @codeend
58+
*
59+
* This will make the docObject look like:
60+
*
61+
* ```
62+
* {memberof: ["_", "lodash"]}
63+
* ```
64+
*
65+
* @signature `@TAG`
66+
*
67+
* Sets a `TAG` property on the docObject to `true`.
68+
*
69+
* @body
70+
*
71+
*/
72+
module.exports = {
673

74+
add: function( line, curData, scope, objects, currentWrite, siteConfig ) {
775

76+
var tag = line.match(matchTag)[1].toLowerCase(),
77+
value = line.replace(matchTag,"").trim();
878

9-
/**
10-
* @constructor documentjs.tags._default @_default
11-
* @tag documentation
12-
* @parent documentjs.tags
13-
* @hide
14-
*
15-
* The default tag behavior when `@TAG` begins a line, but no
16-
* tag is defined for `TAG`.
17-
*
18-
*
19-
*
20-
* @signature `@TAG NAME[, ...]`
21-
*
22-
* Sets a `TAG` property on the docObject to `"NAME"`.
23-
*
24-
* Example:
25-
* @codestart javascript
26-
* /**
27-
* * @@memberOf _
28-
* *|
29-
* findById: function( id, success ) {
30-
* @codeend
31-
*
32-
* This will make the docObject look like:
33-
*
34-
* ```
35-
* {memberof: "_"}
36-
* ```
37-
*
38-
* If `NAME` values are seperated by comma-space (`, `), the values will be set as an array. Example:
39-
*
40-
*
41-
*
42-
* @codestart javascript
43-
* /**
44-
* * @@memberOf _, lodash
45-
* *|
46-
* findById: function( id, success ) {
47-
* @codeend
48-
*
49-
* This will make the docObject look like:
50-
*
51-
* ```
52-
* {memberof: ["_", "lodash"]}
53-
* ```
54-
*
55-
* If multiple `@TAG NAME`s are found with the same `TAG`, an array with each
56-
* `"NAME"` will be created. Example:
57-
*
58-
* @codestart javascript
59-
* /**
60-
* * @@memberOf _
61-
* * @@memberOf lodash
62-
* *|
63-
* findById: function( id, success ) {
64-
* @codeend
65-
*
66-
* This will make the docObject look like:
67-
*
68-
* ```
69-
* {memberof: ["_", "lodash"]}
70-
* ```
71-
*
72-
* @signature `@TAG`
73-
*
74-
* Sets a `TAG` property on the docObject to `true`.
75-
*
76-
* @body
77-
*
78-
*/
79-
module.exports = {
80-
81-
add: function( line, curData, scope, objects, currentWrite, siteConfig ) {
82-
83-
var tag = line.match(matchTag)[1].toLowerCase(),
84-
value = line.replace(matchTag,"").trim();
85-
86-
if(value.indexOf(", ") >= 0) {
87-
value = value.split(", ").map(function(val){
88-
return val.trim();
89-
});
90-
}
91-
if(value && typeof value === "string") {
92-
value = [value];
93-
}
79+
if(value.indexOf(", ") >= 0) {
80+
value = value.split(", ").map(function(val){
81+
return val.trim();
82+
});
83+
}
84+
if(value && typeof value === "string") {
85+
value = [value];
86+
}
9487

95-
suggestType(siteConfig.tags, tag, this.line, this.src);
88+
suggestType(siteConfig.tags, tag, this.line, this.src);
9689

97-
if(value) {
98-
if( Array.isArray(this[tag]) ){
99-
this[tag].push.apply(this[tag], value);
100-
} else if( this[tag] && tag != "name"){
101-
this[tag] = [this[tag]].concat(value);
102-
} else {
103-
this[tag] = value.length > 1 ? value : value[0];
104-
}
90+
if(value) {
91+
if( Array.isArray(this[tag]) ){
92+
this[tag].push.apply(this[tag], value);
93+
} else if( this[tag] && tag != "name"){
94+
this[tag] = [this[tag]].concat(value);
10595
} else {
106-
this[tag] = true;
96+
this[tag] = value.length > 1 ? value : value[0];
10797
}
108-
98+
} else {
99+
this[tag] = true;
109100
}
110-
};
111101

102+
}
103+
};
112104

113105
function suggestType(tags, incorrect, line, src ) {
114106
var lowest = 1000,

‎tags/add.js

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,29 @@
1-
21
/**
3-
* @constructor documentjs.tags.add @add
4-
* @parent documentjs.tags
2+
* @parent bit-docs-process-tags/tags
3+
* @module {bit-docs-js/tag} bit-docs-process-tags/tags/add @add
54
*
65
* @description
76
*
8-
* Sets a [documentjs.process.docObject] as the
9-
* current scope.
7+
* Sets a [bit-docs/types/docObject docObject] as the current scope.
108
*
119
* @signature `@add NAME`
1210
*
13-
* @param {STRING} NAME The name of [documentjs.process.docObject]
14-
* to set as the scope.
11+
* @param {STRING} NAME The name of [bit-docs/types/docObject docObject] to set
12+
* as the scope.
1513
*
1614
* @body
1715
*
1816
* ## Use
1917
*
20-
* [documentjs.tags.function]
21-
* or [documentjs.tags.property] tags created
22-
* without a name, or with a "short name" will use the current
23-
* scope to guess their full name and parent. `@add` can set the scope,
24-
* allowing comments to not have to write out a full name and [documentjs.tags.parent] tag.
18+
* [bit-docs-js/tags/function] or [bit-docs-js/tags/property] tags created
19+
* without a name, or with a "short name" will use the current scope to guess
20+
* their full name and parent. `@add` can set the scope, allowing comments to
21+
* not have to write out a full name and [bit-docs-process-tags/tags/parent]
22+
* tag.
2523
*
2624
* In the following example, a docObject named `lib.Component.prototype.plugin`
27-
* and `lib.Component.prototype.draw` will be created, each with `lib.Component.prototype`
28-
* as their parent.
25+
* and `lib.Component.prototype.draw` will be created, each with
26+
* `lib.Component.prototype` as their parent.
2927
*
3028
* @codestart javascript
3129
* /** @@add lib.Component.prototype *|

‎tags/body.js

Lines changed: 21 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,33 @@
1-
var startHTMLComment = /\s*<!--/,
2-
endHTMLComment = /\s*-->/;
1+
var startHTMLComment = /\s*<!--/;
2+
var endHTMLComment = /\s*-->/;
3+
34
/**
4-
* @constructor documentjs.tags.body @body
5-
* @parent documentjs.tags
5+
* @parent bit-docs-process-tags/tags
6+
* @module {bit-docs-js/tag} bit-docs-process-tags/tags/body @body
67
*
78
* @description
89
*
910
* Markdown content placed after all signature and API content.
1011
*
1112
* @signature `@body`
1213
*
13-
* Content after the `@body` tag appears after
14-
* the title, description, signature and API content.
14+
* Content after the `@body` tag appears after the title, description,
15+
* signature and API content.
1516
*
16-
* `@body` tag content is treated as markdown and set as
17-
* the [documentjs.process.docObject]'s `body` property.
17+
* `@body` tag content is treated as markdown and set as the
18+
* [bit-docs/types/docObject docObject]'s `body` property.
1819
*
1920
* @body
2021
*
2122
* ## Use
2223
*
23-
* The body of a [documentjs.process.docObject] is displayed at the bottom
24-
* of an html page generated with
25-
* the [documentjs.generators.html default html generator].
24+
* The body of a [bit-docs/types/docObject docObject] is displayed at the
25+
* bottom of an html page generated with the
26+
* [bit-docs-generate-html default html generator].
2627
*
27-
* In the following example, `@body` stops content from being added to [documentjs.tags.param],
28-
* and instead makes content be added to the body property.
28+
* In the following example, `@body` stops content from being added to
29+
* [bit-docs-js/tags/param], and instead makes content be added to the body
30+
* property.
2931
*
3032
* @codestart javascript
3133
* /**
@@ -45,12 +47,13 @@ var startHTMLComment = /\s*<!--/,
4547
* lib.Component = function(name){}
4648
* @codeend
4749
*
48-
* By default
49-
* the first paragraph of content that is not after a multi-line tag like [documentjs.tags.signature],
50-
* [documentjs.tags.param], etc, is set as the [documentjs.tags.description]. All content
51-
* after the first paragraph is set as the body content.
50+
* By default the first paragraph of content that is not after a multi-line tag
51+
* like [bit-docs-js/tags/signature], [bit-docs-js/tags/param], etc, is set as
52+
* the [bit-docs-process-tags/tags/description]. All content after the first
53+
* paragraph is set as the body content.
5254
*
53-
* You can see what is treated as description and body by default in the following example:
55+
* You can see what is treated as description and body by default in the
56+
* following example:
5457
*
5558
* @codestart javascript
5659
* /**
@@ -72,9 +75,6 @@ var startHTMLComment = /\s*<!--/,
7275
* *|
7376
* Graph.prototype.cols = function(cols){ ... }
7477
* @codeend
75-
*
76-
*
77-
*
7878
*/
7979
module.exports= {
8080
add: function( line ) {

0 commit comments

Comments
 (0)