Skip to content

Commit 1df46fc

Browse files
chasenleharachasenlehara
authored
Merge pull request #5 from bit-docs/docs
docs
2 parents 46cfd2e + fe400f6 commit 1df46fc

File tree

6 files changed

+469
-450
lines changed

6 files changed

+469
-450
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# bit-docs-js

‎bit-docs.js

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,12 +5,36 @@ var path = require("path");
55
/**
66
* @module {function} bit-docs-js
77
* @parent plugins
8+
* @group bit-docs-js/tags tags
89
*
9-
* @description A collection of tags, templates, and basic styles for JavaScript applications.
10+
* @description Tags, templates, and basic styles for JavaScript.
1011
*
12+
* @param {Object} [bitDocs] The configuration object passed by `bit-docs` at
13+
* runtime.
14+
*
1115
* @body
16+
*
17+
* This plugin registers onto these hooks:
18+
* - `tags`
19+
* - `processor`
20+
* - `html`
21+
*
22+
* Registering the `tag` hook adds JavaScript-related tags:
23+
* - [bit-docs-js/tags/function @function]
24+
* - [bit-docs-js/tags/param @param]
25+
* - [bit-docs-js/tags/signature @signature]
26+
* - ...
27+
*
28+
* Registering the `processor` hook adds a processor for `*.js` files that gets
29+
* code comments in JavaScript, and processes tags like `@function` and
30+
* `@param` into docObjects that are subsequently added to the docMap.
1231
*
13-
* TBD
32+
* The processor is also smart enough process regular comments above functions
33+
* that have not explicitly been documented with closure type annotations, and
34+
* extracts basic signature information such as parameters and/or return type.
35+
*
36+
* Registering the `html` hook adds a mustache template used to generate the
37+
* HTML for the tags added by this plugin.
1438
*/
1539
module.exports = function(bitDocs){
1640
// register your tags

‎tags/function.js

Lines changed: 106 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,119 @@
1-
var getParent = require("bit-docs-process-tags/get-parent"),
2-
tnd = require("bit-docs-type-annotate").typeNameDescription;
3-
4-
//(~)? is just a stupid way of making sure there are the right number of parts
5-
6-
// key: function() or key= function(){}
7-
keyFunction = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[:=].*function\s?\(([^\)]*)/,
8-
namedFunction = /\s*function\s+([\w\.\$]+)\s*(~)?\(([^\)]*)/;
9-
1+
var updateNameWithScope = require("../lib/updateNameAndParentWithScope");
2+
var getParent = require("bit-docs-process-tags/get-parent");
3+
var tnd = require("bit-docs-type-annotate").typeNameDescription;
4+
5+
// key: function() or key= function(){}
6+
//(~)? is just a stupid way of making sure there are the right number of parts
7+
keyFunction = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[:=].*function\s?\(([^\)]*)/;
8+
namedFunction = /\s*function\s+([\w\.\$]+)\s*(~)?\(([^\)]*)/;
9+
10+
/**
11+
* @module {Object} bit-docs-js/tags/function @function
12+
* @parent bit-docs-js/tags
13+
*
14+
* @description Specifies the comment is for a function. Use
15+
* [bit-docs-js/tags/param] to specify the parameters of a function.
16+
*
17+
* @signature `@function [NAME] [TITLE]`
18+
*
19+
* @codestart javascript
20+
* /**
21+
* * @function lib.Component.prototype.update update
22+
* * @parent lib.Component
23+
* *|
24+
* C.p.update = function(){
25+
*
26+
* }
27+
* @codeend
28+
*
29+
* @param {String} [NAME] The name of the function. It should be supplied
30+
* if it cannot be determined from the code block following the comment.
31+
*
32+
* @param {String} [TITLE] The title to be used for display purposes.
33+
*
34+
* @body
35+
*
36+
* ## Code Matching
37+
*
38+
* The `@function` type can be inferred from code like the following:
39+
*
40+
* @codestart javascript
41+
* /**
42+
* * The foo function exists
43+
* *|
44+
* foo: function(){}
45+
*
46+
* /**
47+
* * The bar function exists
48+
* *|
49+
* bar = function(){}
50+
* @codeend
51+
*/
52+
module.exports = {
53+
codeMatch: /function(\s+[\w\.\$]+)?\s*\([^\)]*\)/,
54+
code: function (code, scope, docMap) {
55+
var parts = code.match(keyFunction);
56+
57+
if (!parts) {
58+
parts = code.match(namedFunction);
59+
}
1060

61+
var data = {
62+
type: "function"
63+
};
1164

12-
var updateNameWithScope = require("../lib/updateNameAndParentWithScope");
65+
if (!parts) {
66+
return;
67+
}
1368

14-
/**
15-
* @constructor documentjs.tags.function @function
16-
*
17-
* @parent documentjs.tags
18-
*
19-
* @description Specifies the comment is for a function. Use [documentjs.tags.param @param] to
20-
* specify the arguments of a function.
21-
*
22-
* @signature `@function [NAME] [TITLE]`
23-
*
24-
* @codestart javascript
25-
* /**
26-
* * @function lib.Component.prototype.update update
27-
* * @parent lib.Component
28-
* *|
29-
* C.p.update = function(){
30-
*
31-
* }
32-
* @codeend
33-
*
34-
* @param {String} [NAME] The name of the function. It should
35-
* be supplied if it can not be determined from the code block
36-
* following the comment.
37-
*
38-
* @param {String} [TITLE] The title to be used for display purposes.
39-
*
40-
* @body
41-
*
42-
* ## Code Matching
43-
*
44-
* The `@function` type can be infered from code like the following:
45-
*
46-
* @codestart javascript
47-
* /**
48-
* * The foo function exists
49-
* *|
50-
* foo: function(){}
51-
* /**
52-
* * The bar function exists
53-
* *|
54-
* bar = function(){}
55-
* @codeend
56-
*/
57-
module.exports = {
58-
codeMatch: /function(\s+[\w\.\$]+)?\s*\([^\)]*\)/,
59-
code: function( code, scope, docMap ) {
69+
data.name = parts[1] ? parts[1].replace(/^this\./, "")
70+
.replace(/^exports\./, "")
71+
.replace(/^\$./, "jQuery.") : parts[2];
6072

61-
var parts = code.match(keyFunction);
73+
data.params = [];
74+
var params = parts[3].match(/\w+/g);
6275

63-
if (!parts ) {
64-
parts = code.match(namedFunction);
65-
}
66-
var data = {
67-
type: "function"
68-
};
69-
if (!parts ) {
70-
return;
76+
if (params) {
77+
for (var i = 0; i < params.length; i++) {
78+
data.params.push({
79+
name: params[i],
80+
types: [{ type: "*" }]
81+
});
7182
}
72-
data.name = parts[1] ? parts[1].replace(/^this\./, "")
73-
.replace(/^exports\./, "")
74-
.replace(/^\$./, "jQuery.") : parts[2];
75-
76-
77-
data.params = [];
78-
var params = parts[3].match(/\w+/g);
79-
80-
if ( params ) {
83+
}
8184

82-
for ( var i = 0; i < params.length; i++ ) {
83-
data.params.push({
84-
name: params[i],
85-
types: [{type: "*"}]
86-
});
87-
}
85+
// assign name and parent
86+
if (scope && docMap) {
87+
var parentAndName = getParent.andName({
88+
parents: "*",
89+
useName: ["constructor", "static", "prototype", "add", "module"],
90+
scope: scope,
91+
docMap: docMap,
92+
name: data.name
93+
});
94+
95+
data.parent = parentAndName.parent;
96+
data.name = parentAndName.name;
97+
}
8898

89-
}
99+
return data;
100+
},
101+
add: function (line, curData, scope, docMap) {
102+
var data = tnd(line);
103+
this.title = data.description;
90104

91-
// assign name and parent
92-
if(scope && docMap){
93-
var parentAndName = getParent.andName({
94-
parents: "*",
95-
useName: ["constructor","static","prototype","add","module"],
96-
scope: scope,
97-
docMap: docMap,
98-
name: data.name
99-
});
105+
if (data.name) {
106+
this.name = data.name;
107+
}
100108

101-
data.parent = parentAndName.parent;
102-
data.name = parentAndName.name;
103-
}
109+
updateNameWithScope(this, scope, docMap);
104110

105-
return data;
106-
},
107-
add: function(line, curData, scope, docMap){
108-
var data = tnd(line);
109-
this.title = data.description;
110-
if(data.name) {
111-
this.name = data.name;
112-
}
113-
updateNameWithScope(this, scope, docMap);
114-
if(this.name)
111+
if (this.name) {
115112
this.type = "function";
116-
if(!data.params){
117-
data.params = [];
118-
}
119113
}
120-
};
114+
115+
if (!data.params) {
116+
data.params = [];
117+
}
118+
}
119+
};

0 commit comments

Comments
 (0)