Skip to content

Commit 11dbdc9

Browse files
leoj3nleoj3n
committed
Layout example theme-path-literal
1 parent 2481dcd commit 11dbdc9

File tree

5 files changed

+128
-19
lines changed

5 files changed

+128
-19
lines changed

‎bit-docs.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ var path = require("path");
66
* @parent plugins
77
* @module {function} bit-docs-js
88
* @group bit-docs-js/tags tags
9-
* @group bit-docs-js/templates templates
9+
* @group bit-docs-js/theme theme
1010
*
1111
* @description Tags, templates, and basic styles for JavaScript.
1212
*

‎tags/function.js

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,24 @@ namedFunction = /\s*function\s+([\w\.\$]+)\s*(~)?\(([^\)]*)/;
1818
*
1919
* @codestart javascript
2020
* /**
21+
* * @module {{}} lib.component Component
22+
* *|
23+
*
24+
* /**
2125
* * @function lib.Component.prototype.update update
2226
* * @parent lib.Component
2327
* *|
24-
* C.p.update = function(){
25-
*
28+
* C.p.update = function(){ /* ... *| }
29+
*
30+
* // resulting docObject
31+
* {
32+
* "type": "function",
33+
* "name": "lib.Component.prototype.update",
34+
* "params": [],
35+
* "parent": "lib.Component",
36+
* "description": "\n",
37+
* "title": "update",
38+
* "pathToRoot": ".."
2639
* }
2740
* @codeend
2841
*

‎tags/option.js

Lines changed: 107 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -61,18 +61,25 @@ var setOptionData = function (option, data) {
6161
*
6262
* @signature `@option {TYPE} NAME [DESCRIPTION]`
6363
*
64+
* Here's an example of some ways you can use the `@option` tag:
65+
*
6466
* @codestart javascript
6567
* /**
66-
* * Retrieves a list of orders.
67-
* *
68-
* * @param {{}} params A parameter object with the following options:
69-
* * @option {String} type Specifies the type of order.
70-
* * @option {Number} [createdAt] Retrieves orders after this timestamp.
71-
* *
72-
* * @param {function(Orders.List)} [success(orders)] Callback function.
73-
* * @option orders A list of [Orders] that match `params`.
68+
* * @module {{}} ledger Ledger
7469
* *|
75-
* find: function( params, success ) { ... }
70+
* module.exports = {
71+
* /**
72+
* * Retrieves a list of orders.
73+
* *
74+
* * @param {{}} params A parameter object with the following options:
75+
* * @option {String} type Specifies the type of order.
76+
* * @option {Number} [createdAt] Retrieves orders after this timestamp.
77+
* *
78+
* * @param {function(Orders.List)} [success(orders)] Callback function.
79+
* * @option orders A list of [Orders] that match `params`.
80+
* *|
81+
* find: function(params, success) { /*...*| }
82+
* };
7683
* @codeend
7784
*
7885
* @param {bit-docs/typeExpression} [TYPE] A [bit-docs/typeExpression type expression]. Examples:
@@ -88,18 +95,107 @@ var setOptionData = function (option, data) {
8895
* @codestart
8996
* /**
9097
* * @param {{type: String}} params An object with the following options:
91-
* * @option type Specifies the type of order.
92-
* * @option label Retrieves only orders with this label.
98+
* * @option type Specifies the type of order.
99+
* * @option label Retrieves only orders with this label.
93100
* *|
94101
* @codeend
95102
*
103+
* However, omitting TYPE might confuse your team members, so we recommend
104+
* being explicit and always specifying TYPE for `@option`.
105+
*
96106
* @param {bit-docs/nameExpression} NAME A [bit-docs/nameExpression name expression]. Examples:
97107
*
98108
* `age` - age is item.
99109
* `[age]` - age is item, age is optional.
100110
* `[age=0]` - age defaults to 0.
101111
*
102112
* @param {Markdown} [DESCRIPTION] Markdown content that continues for multiple lines.
113+
*
114+
* @body
115+
*
116+
* ### Usage Examples
117+
*
118+
* @codestart javascript
119+
* /**
120+
* * @module {{}} foo Foo
121+
* *|
122+
* module.exports = {
123+
* /**
124+
* * A function named bar.
125+
* *
126+
* * @param {{}} params A parameter object with options:
127+
* * @option {String} aString An arbitrary string.
128+
* * @option {Number} [oNumber] An optional number.
129+
* *|
130+
* bar: function(params) { /*...*| }
131+
* };
132+
* @codeend
133+
*
134+
* Resulting [bit-docs/types/docObject]:
135+
*
136+
* @codestart javascript
137+
* {
138+
* "type": "function",
139+
* "name": "foo.bar",
140+
* "params": [
141+
* {
142+
* "types": [
143+
* {
144+
* "type": "Object",
145+
* "options": [
146+
* {
147+
* "name": "aString",
148+
* "description": "An arbitrary string.",
149+
* "types": [
150+
* {
151+
* "type": "String"
152+
* }
153+
* ]
154+
* },
155+
* {
156+
* "name": "oNumber",
157+
* "description": "An optional number.\n",
158+
* "types": [
159+
* {
160+
* "type": "Number"
161+
* }
162+
* ],
163+
* "optional": true
164+
* }
165+
* ]
166+
* }
167+
* ],
168+
* "name": "params",
169+
* "description": "A parameter object with options:"
170+
* }
171+
* ],
172+
* "parent": "foo",
173+
* "description": "A function named bar.\n"
174+
* }
175+
* @codeend
176+
*
177+
* That [bit-docs/types/docObject] an be used in a template like this:
178+
*
179+
* @codestart html
180+
* {{#if params}}
181+
* {{#params}}
182+
* {{#types}}
183+
* {{#if options.length}}
184+
* {{#options}}
185+
* <p>
186+
* Option Name: {{name}}
187+
* <br/>
188+
* Option Description: {{description}}
189+
* </p>
190+
* {{/options}}
191+
* {{/if}}
192+
* {{/types}}
193+
* {{/params}}
194+
* {{/if}}
195+
* @codeend
196+
*
197+
* See [signature.mustache] for a more complex template that uses the
198+
* [bit-docs/types/docObject] resulting from `@option`.
103199
*/
104200
module.exports = {
105201
addMore: function (line, last) {

‎tags/param.js

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ var addParam = function (param, params) {
3535

3636
/**
3737
* @parent bit-docs-js/tags
38-
* @module {Object} bit-docs-js/tags/param @param
38+
* @module {bit-docs-js/tag} bit-docs-js/tags/param @param
3939
*
4040
* Specifies parameter information for [bit-docs-js/tags/function] or
4141
* [bit-docs-js/tags/signature].
@@ -58,8 +58,8 @@ var addParam = function (param, params) {
5858
*
5959
* @param {bit-docs-js/typeExpression} TYPE A [bit-docs-js/typeExpression type expression].
6060
*
61-
* Use [bit-docs-js/tags/option @option] to describe a function's arguments,
62-
* or an object's properties.
61+
* Use [bit-docs-js/tags/option @option] to describe a function's arguments, or
62+
* an object's properties.
6363
*
6464
* @param {bit-docs-js/nameExpression} NAME A [bit-docs-js/nameExpression name expression].
6565
*

‎templates/signature.mustache.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
@parent bit-docs-js/templates
2-
@page bit-docs-js/templates/signature signature
1+
@parent bit-docs-js/theme
2+
@module bit-docs-js/site/templates/signature.mustache signature.mustache
33

44
@description The function signature template.
55

0 commit comments

Comments
 (0)