Skip to content

Commit c41446d

Browse files
leoj3nleoj3n
committed
WIP
1 parent fe400f6 commit c41446d

File tree

4 files changed

+122
-61
lines changed

4 files changed

+122
-61
lines changed

‎tags/function.js

Lines changed: 66 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ namedFunction = /\s*function\s+([\w\.\$]+)\s*(~)?\(([^\)]*)/;
1111
* @module {Object} bit-docs-js/tags/function @function
1212
* @parent bit-docs-js/tags
1313
*
14-
* @description Specifies the comment is for a function. Use
14+
* @description Specifies the comment block is for a function. Use
1515
* [bit-docs-js/tags/param] to specify the parameters of a function.
1616
*
1717
* @signature `@function [NAME] [TITLE]`
@@ -46,7 +46,71 @@ namedFunction = /\s*function\s+([\w\.\$]+)\s*(~)?\(([^\)]*)/;
4646
* /**
4747
* * The bar function exists
4848
* *|
49-
* bar = function(){}
49+
* bar = function(buz, baz){
50+
* return 'a string';
51+
* }
52+
* @codeend
53+
*
54+
* The comment block above `foo` will automatically be associated with the
55+
* function `foo`. Essentially, as if it had been explicitly written as:
56+
*
57+
* @codestart javascript
58+
* /**
59+
* * @function lib.foo foo
60+
* * @description The foo function exists
61+
* *|
62+
* foo: function(){}
63+
* @codeend
64+
*
65+
* The same is true for the comment block above `bar`, which translates to:
66+
*
67+
* @codestart javascript
68+
* /**
69+
* * @function lib.bar bar
70+
* * @param {*} buz
71+
* * @param {*} baz
72+
* * @return {String}
73+
* * @description The bar function exists
74+
* *|
75+
* bar = function(buz, baz){
76+
* return 'a string';
77+
* }
78+
* @codeend
79+
*
80+
* Furthermore, the code matching can handle prototypes and methods like:
81+
*
82+
* @codestart javascript
83+
* /**
84+
* * @module {function} foo-bar
85+
* *|
86+
* Foo = function(){};
87+
* Object.assign(Foo.prototype, {
88+
* bar: function(arg1){}
89+
* });
90+
* module.exports = Foo;
91+
* @codeend
92+
*
93+
* Which translates to:
94+
*
95+
* @codestart javascript
96+
* /**
97+
* * @module {function} foo-bar
98+
* *|
99+
* Foo = function(){};
100+
*
101+
* /**
102+
* * @prototype
103+
* *|
104+
* Object.assign(Foo.prototype, {
105+
*
106+
* /**
107+
* * The bar function exists
108+
* *|
109+
* bar: function(arg1){}
110+
*
111+
* });
112+
*
113+
* module.exports = Foo;
50114
* @codeend
51115
*/
52116
module.exports = {

‎tags/option.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -53,7 +53,7 @@ var setOptionData = function (option, data) {
5353
};
5454

5555
/**
56-
* @module bit-docs-js/tags/option @option
56+
* @module {bit-docs-process-tags/tag} bit-docs-js/tags/option @option
5757
* @tag documentation
5858
* @parent bit-docs-js/tags
5959
*

‎tags/property.js

Lines changed: 30 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,37 +1,36 @@
11
var getParent = require("bit-docs-process-tags/get-parent"),
22
tnd = require("bit-docs-type-annotate").typeNameDescription,
33
updateNameWithScope = require("../lib/updateNameAndParentWithScope");
4-
/**
5-
* @constructor documentjs.tags.property @property
6-
* @parent documentjs.tags
7-
*
8-
* Documents a property of a parent object.
9-
*
10-
* @signature `@property {TYPE} NAME [TITLE]` Documents a
11-
* property named `NAME` of type `{TYPE}`.
12-
*
13-
* @codestart
14-
* /**
15-
* * @@property {Number} delay
16-
* * Sets the delay in milliseconds between an ajax request is made and
17-
* * the success and complete handlers are called. This only sets
18-
* * functional fixtures. By default, the delay is 200ms.
19-
* *|
20-
* $.fixture.delay = 200
21-
* @codeend
22-
*
23-
* @param {documentjs.typeExpression} [TYPE] An optional type like `{Object}`.
24-
* @param {documentjs.nameExpression} [NAME] The name of the property. This maybe infered from the
25-
* code block immediately following the comment.
26-
* @param {STRING} [TITLE] The display title of the property.
27-
*
28-
* @signature `["']?(\w+)["']?\s*[:=]\s*`
29-
*
30-
* If code matches the above regular expression and is not a function, it is
31-
* automatically assumed to be a property.
32-
*
33-
*
34-
*/
4+
5+
/**
6+
* @module {bit-docs-process-tags/tag} bit-docs-js/tags/property @property
7+
* @parent bit-docs-js/tags
8+
*
9+
* Documents a property of a parent object.
10+
*
11+
* @signature `@property {TYPE} NAME [TITLE]` Documents a property named `NAME`
12+
* of type `{TYPE}`.
13+
*
14+
* @codestart
15+
* /**
16+
* * @@property {Number} delay
17+
* * Sets the delay in milliseconds between an ajax request is made and
18+
* * the success and complete handlers are called. This only sets
19+
* * functional fixtures. By default, the delay is 200ms.
20+
* *|
21+
* $.fixture.delay = 200
22+
* @codeend
23+
*
24+
* @param {bit-docs-js/tags/typeExpression} [TYPE] An optional type like `{Object}`.
25+
* @param {bit-docs-js/tags/nameExpression} [NAME] The name of the property.
26+
* This maybe inferred from the code block immediately following the comment.
27+
* @param {STRING} [TITLE] The display title of the property.
28+
*
29+
* @signature `["']?(\w+)["']?\s*[:=]\s*`
30+
*
31+
* If code matches the above regular expression and is not a function, it is
32+
* automatically assumed to be a property.
33+
*/
3534
module.exports = {
3635
codeMatch: function( code ) {
3736
return code.match(/["']?(\w+)["']?\s*[:=]\s*/) && !code.match(/["']?(\w+)["']?\s*[:=]\s*function\(([^\)]*)/);

‎tags/prototype.js

Lines changed: 25 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,31 @@
11
var getParent = require("bit-docs-process-tags/get-parent"),
22
tnd = require("bit-docs-type-annotate").typeNameDescription;
33

4-
/**
5-
* @constructor documentjs.tags.prototype @prototype
6-
* @parent documentjs.tags
7-
*
8-
* Declares that [documentjs.tags.property] and
9-
* [documentjs.tags.function] tags belong
10-
* to the preceeding [documentjs.tags.function]'s
11-
* prototype object.
12-
*
13-
* @signature `@prototype`
14-
*
15-
* @codestart javascript
16-
* /**
17-
* * @@function
18-
* * Creates an Animal
19-
* *|
20-
* Animal = function(){ ... }
21-
* /** @@prototype *|
22-
* Animal.prototype = {
23-
* /**
24-
* * Eats another animal.
25-
* *|
26-
* eat: function(animal){ ... }
27-
* }
28-
* @codeend
29-
*
30-
*/
4+
/**
5+
* @module {bit-docs-process-tags/tag} bit-docs-js/tags/prototype @prototype
6+
* @parent bit-docs-js/tags
7+
*
8+
* Declares that [bit-docs-js/tags/property] and [bit-docs-js/tags/function]
9+
* tags belong to the preceeding [bit-docs-js/tags/function]'s prototype
10+
* object.
11+
*
12+
* @signature `@prototype`
13+
*
14+
* @codestart javascript
15+
* /**
16+
* * @@function
17+
* * Creates an Animal
18+
* *|
19+
* Animal = function(){ ... }
20+
* /** @@prototype *|
21+
* Animal.prototype = {
22+
* /**
23+
* * Eats another animal.
24+
* *|
25+
* eat: function(animal){ ... }
26+
* }
27+
* @codeend
28+
*/
3129
module.exports = {
3230
add: function(line, curData, scope, docMap){
3331

0 commit comments

Comments
 (0)