Skip to content

Commit f9720b3

Browse files
justinbmeyerjustinbmeyer
committed
simple added tags
0 parents  commit f9720b3

25 files changed

+2029
-0
lines changed

‎.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
node_modules

‎package.json

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"name": "bit-docs-js",
3+
"version": "0.0.1",
4+
"description": "tags and templates for JS apps",
5+
"main": "index.js",
6+
"scripts": {
7+
"test": "echo \"Error: no test specified\" && exit 1"
8+
},
9+
"repository": {
10+
"type": "git",
11+
"url": "git+https://github.com/bit-docs/bit-docs-js.git"
12+
},
13+
"keywords": [
14+
"bit-docs",
15+
"donejs"
16+
],
17+
"author": "Bitovi",
18+
"license": "MIT",
19+
"bugs": {
20+
"url": "https://github.com/bit-docs/bit-docs-js/issues"
21+
},
22+
"homepage": "https://github.com/bit-docs/bit-docs-js#readme"
23+
}

‎tags/class.js

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
var getParent = require("./helpers/getParent"),
2+
tnd = require("./helpers/typeNameDescription");
3+
4+
var funcMatch = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[=]\s*function\s?\(([^\)]*)/,
5+
codeMatch = /([\w\.\$]+?).extend\(\s*["']([^"']*)["']/;
6+
7+
/**
8+
* @constructor documentjs.tags.constructor @constructor
9+
* @hide
10+
* Document a constructor function.
11+
*
12+
* @signature `@constructor NAME [TITLE]`
13+
* @parent documentjs.tags
14+
*/
15+
module.exports = {
16+
add: function(line, curData, scope, docMap){
17+
console.warn("Using the @class directive. It is deprecated!");
18+
// it's possible this has already been matched as something else ... clear parent
19+
20+
this.type = "constructor";
21+
var data = tnd(line);
22+
if(data.name) {
23+
this.name = data.name;
24+
}
25+
26+
this.title = data.description;
27+
return ["scope",this];
28+
}
29+
};
30+

‎tags/codeend.js

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
/**
2+
* @hide
3+
* @constructor documentjs.tags.codeend @codeend
4+
* @tag documentation
5+
* @parent documentjs.tags
6+
*
7+
* @description
8+
*
9+
* Stops a code block.
10+
*
11+
* ###Example:
12+
*
13+
* @codestart
14+
*
15+
* /*
16+
* * @codestart
17+
* * /* @class
18+
* * * Person represents a human with a name. Read about the
19+
* * * animal class [Animal | here].
20+
* * * @constructor
21+
* * * You must pass in a name.
22+
* * * @param {String} name A person's name
23+
* * *|
24+
* * Person = function(name){
25+
* * this.name = name
26+
* * Person.count ++;
27+
* * }
28+
* * /* @Static *|
29+
* * steal.Object.extend(Person, {
30+
* * /* Number of People *|
31+
* * count: 0
32+
* * })
33+
* * /* @Prototype *|
34+
* * Person.prototype = {
35+
* * /* Returns a formal name
36+
* * * @return {String} the name with "Mrs." added
37+
* * *|
38+
* * fancyName : function(){
39+
* * return "Mrs. "+this.name;
40+
* * }
41+
* * }
42+
* * @codeend
43+
* *|
44+
*
45+
* @codeend
46+
*/
47+
module.exports = {
48+
add: function( line, data ) {
49+
50+
if (!data.lines ) {
51+
console.warn('you probably have a @codeend without a @codestart')
52+
}
53+
54+
var joined = data.lines.join("\n");
55+
56+
if ( data.type == "javascript" || data.type == "js") { //convert comments
57+
joined = joined.replace(/\*\|/g, "*/")
58+
}
59+
var out = "```" + data.type + "\n"
60+
+ joined.replace(/&lt;/g,"<")
61+
.replace(/&gt;/g,">")
62+
.replace(/&amp;/g,"&") +
63+
"\n```";
64+
65+
return ["poppop", out];
66+
},
67+
keepStack: true
68+
};

‎tags/codestart.js

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
/**
2+
* @constructor documentjs.tags.codestart @codestart
3+
* @hide
4+
* @parent documentjs.tags
5+
*
6+
* Starts a code block.
7+
*
8+
* Looks for "@codestart codeType".
9+
*
10+
* Matches multiple lines.
11+
*
12+
* Must end with "@codeend".
13+
*
14+
* ###Example:
15+
*
16+
* @codestart
17+
*
18+
* /*
19+
* * @codestart
20+
* * /* @class
21+
* * * Person represents a human with a name. Read about the
22+
* * * animal class [Animal | here].
23+
* * * @constructor
24+
* * * You must pass in a name.
25+
* * * @param {String} name A person's name
26+
* * *|
27+
* * Person = function(name){
28+
* * this.name = name
29+
* * Person.count ++;
30+
* * }
31+
* * /* @Static *|
32+
* * steal.Object.extend(Person, {
33+
* * /* Number of People *|
34+
* * count: 0
35+
* * })
36+
* * /* @Prototype *|
37+
* * Person.prototype = {
38+
* * /* Returns a formal name
39+
* * * @return {String} the name with "Mrs." added
40+
* * *|
41+
* * fancyName : function(){
42+
* * return "Mrs. "+this.name;
43+
* * }
44+
* * }
45+
* * @codeend
46+
* *|
47+
*
48+
* @codeend
49+
*/
50+
module.exports = {
51+
add: function( line, last ) {
52+
var m = line.match(/^\s*@codestart\s*([\w-]*)\s*(.*)/)
53+
54+
55+
if ( m ) {
56+
//
57+
return {
58+
type: m[1] ? m[1].toLowerCase() : 'js',
59+
lines: [],
60+
last: last,
61+
_last: this._last
62+
};
63+
}
64+
65+
},
66+
addMore: function( line, data ) {
67+
data.lines.push(line);
68+
},
69+
keepStack: true
70+
};

‎tags/constructor.js

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
var getParent = require("./helpers/getParent"),
2+
tnd = require("./helpers/typeNameDescription");
3+
4+
var funcMatch = /(?:([\w\.\$]+)|(["'][^"']+["']))\s*[=]\s*function\s?\(([^\)]*)/,
5+
codeMatch = /([\w\.\$]+?).extend\(\s*["']([^"']*)["']/;
6+
7+
/**
8+
* @constructor documentjs.tags.constructor @constructor
9+
* @hide
10+
* Document a constructor function.
11+
*
12+
* @signature `@constructor NAME [TITLE]`
13+
* @parent documentjs.tags
14+
*/
15+
module.exports = {
16+
codeMatch: function(code){
17+
return codeMatch.test(code);
18+
},
19+
code: function( code ) {
20+
21+
var parts = code.match(codeMatch);
22+
if ( parts ) {
23+
return {
24+
name: parts[2],
25+
inherits: parts[1].replace(/^\$./, "jQuery."),
26+
type: "constructor"
27+
};
28+
}
29+
parts = code.match(funcMatch)
30+
31+
if ( parts ) {
32+
return {
33+
name: parts[1] ? parts[1].replace(/^this\./, "") : parts[2],
34+
type: "constructor"
35+
};
36+
}
37+
},
38+
codeScope: true,
39+
add: function(line, curData, scope, docMap){
40+
41+
// it's possible this has already been matched as something else ... clear parent
42+
43+
this.type = "constructor";
44+
var data = tnd(line);
45+
if(data.name) {
46+
this.name = data.name;
47+
}
48+
49+
this.title = data.description;
50+
return ["scope",this];
51+
}
52+
};
53+

‎tags/function.js

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
var getParent = require('./helpers/getParent'),
2+
tnd = require('./helpers/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+
10+
11+
12+
var updateNameWithScope = require("./helpers/updateNameAndParentWithScope");
13+
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 ) {
60+
61+
var parts = code.match(keyFunction);
62+
63+
if (!parts ) {
64+
parts = code.match(namedFunction);
65+
}
66+
var data = {
67+
type: "function"
68+
};
69+
if (!parts ) {
70+
return;
71+
}
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 ) {
81+
82+
for ( var i = 0; i < params.length; i++ ) {
83+
data.params.push({
84+
name: params[i],
85+
types: [{type: "*"}]
86+
});
87+
}
88+
89+
}
90+
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+
});
100+
101+
data.parent = parentAndName.parent;
102+
data.name = parentAndName.name;
103+
}
104+
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)
115+
this.type = "function";
116+
if(!data.params){
117+
data.params = [];
118+
}
119+
}
120+
};
121+

0 commit comments

Comments
 (0)