Skip to content

Commit 9057468

Browse files
hegemonichegemonic
committed
provide more complete documentation in module examples (#131)
1 parent 9dde9c5 commit 9057468

File tree

4 files changed

+140
-28
lines changed

4 files changed

+140
-28
lines changed

‎content/en/howto-amd-modules.md

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,9 +74,13 @@ define('my/shirt', function() {
7474
/** The module's `color` property. */
7575
color: 'black',
7676

77-
/** @constructor */
77+
/**
78+
* Create a new Turtleneck.
79+
* @class
80+
* @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).
81+
*/
7882
Turtleneck: function(size) {
79-
/** The class' `size` property. */
83+
/** The class's `size` property. */
8084
this.size = size;
8185
}
8286
};
@@ -105,7 +109,8 @@ module.
105109
*/
106110
define('my/jacket', function() {
107111
/**
108-
* @constructor
112+
* Create a new jacket.
113+
* @class
109114
* @alias module:my/jacket
110115
*/
111116
var Jacket = function() {
@@ -202,11 +207,21 @@ define('html/utils', function() {
202207
* @exports html/utils
203208
*/
204209
var utils = {
205-
/** Get the value of a property on an element. */
210+
/**
211+
* Get the value of a property on an element.
212+
* @param {HTMLElement} element - The element.
213+
* @param {string} propertyName - The name of the property.
214+
* @return {*} The value of the property.
215+
*/
206216
getStyleProperty: function(element, propertyName) { }
207217
};
208218

209-
/** Determine if an element is in the document head. */
219+
/**
220+
* Determine if an element is in the document head.
221+
* @param {HTMLElement} element - The element.
222+
* @return {boolean} Set to `true` if the element is in the document head,
223+
* `false` otherwise.
224+
*/
210225
utils.isInHead = function(element) { }
211226

212227
return utils;
@@ -217,7 +232,11 @@ define('html/utils', function() {
217232
define('tag', function() {
218233
/** @exports tag */
219234
var tag = {
220-
/** @class */
235+
/**
236+
* Create a new Tag.
237+
* @class
238+
* @param {string} tagName - The name of the tag.
239+
*/
221240
Tag: function(tagName) {
222241
// ...
223242
}

‎content/en/howto-commonjs-modules.md

Lines changed: 45 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -174,12 +174,22 @@ property:
174174
*/
175175

176176
module.exports = {
177-
/** Blend two colors together. */
177+
/**
178+
* Blend two colors together.
179+
* @param {string} color1 - The first color, in hexadecimal format.
180+
* @param {string} color2 - The second color, in hexadecimal format.
181+
* @return {string} The blended color.
182+
*/
178183
blend: function(color1, color2) {
179184
// ...
180185
},
181186

182-
/** Darken a color by the given percentage. */
187+
/**
188+
* Darken a color by the given percentage.
189+
* @param {string} color - The color, in hexadecimal format.
190+
* @param {number} percent - The percentage, ranging from 0 to 100.
191+
* @return {string} The darkened color.
192+
*/
183193
darken: function(color, percent) {
184194
// ..
185195
}
@@ -199,13 +209,23 @@ literal:
199209
*/
200210

201211
module.exports = {
202-
/** Blend two colors together. */
212+
/**
213+
* Blend two colors together.
214+
* @param {string} color1 - The first color, in hexadecimal format.
215+
* @param {string} color2 - The second color, in hexadecimal format.
216+
* @return {string} The blended color.
217+
*/
203218
blend: function(color1, color2) {
204219
// ...
205220
}
206221
};
207222

208-
/** Darken a color by the given percentage. */
223+
/**
224+
* Darken a color by the given percentage.
225+
* @param {string} color - The color, in hexadecimal format.
226+
* @param {number} percent - The percentage, ranging from 0 to 100.
227+
* @return {string} The darkened color.
228+
*/
209229
module.exports.darken = function(color, percent) {
210230
// ..
211231
};
@@ -225,7 +245,12 @@ the function:
225245
* @module color/mixer
226246
*/
227247

228-
/** Blend two colors together. */
248+
/**
249+
* Blend two colors together.
250+
* @param {string} color1 - The first color, in hexadecimal format.
251+
* @param {string} color2 - The second color, in hexadecimal format.
252+
* @return {string} The blended color.
253+
*/
229254
module.exports = function(color1, color2) {
230255
// ...
231256
};
@@ -285,7 +310,12 @@ symbol represents the value exported by a module.
285310
* @exports color/mixer
286311
*/
287312
var mixer = module.exports = {
288-
/** Blend two colors together. */
313+
/**
314+
* Blend two colors together.
315+
* @param {string} color1 - The first color, in hexadecimal format.
316+
* @param {string} color2 - The second color, in hexadecimal format.
317+
* @return {string} The blended color.
318+
*/
289319
blend: function(color1, color2) {
290320
// ...
291321
}
@@ -306,9 +336,16 @@ property is exported by the module:
306336
{% example "Properties added to a module's 'this' object" %}
307337

308338
```js
309-
/** @module bookshelf */
339+
/**
340+
* Module for bookshelf-related utilities.
341+
* @module bookshelf
342+
*/
310343

311-
/** @class */
344+
/**
345+
* Create a new Book.
346+
* @class
347+
* @param {string} title - The title of the book.
348+
*/
312349
this.Book = function(title) {
313350
/** The title of the book. */
314351
this.title = title;

‎howto-amd-modules.html

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,13 @@ <h2 id="function-that-returns-an-object-literal">Function that returns an object
8585
/** The module's `color` property. */
8686
color: 'black',
8787

88-
/** @constructor */
88+
/**
89+
* Create a new Turtleneck.
90+
* @class
91+
* @param {string} size - The size (`XS`, `S`, `M`, `L`, `XL`, or `XXL`).
92+
*/
8993
Turtleneck: function(size) {
90-
/** The class' `size` property. */
94+
/** The class's `size` property. */
9195
this.size = size;
9296
}
9397
};
@@ -107,7 +111,8 @@ <h2 id="function-that-returns-another-function">Function that returns another fu
107111
*/
108112
define('my/jacket', function() {
109113
/**
110-
* @constructor
114+
* Create a new jacket.
115+
* @class
111116
* @alias module:my/jacket
112117
*/
113118
var Jacket = function() {
@@ -175,11 +180,21 @@ <h2 id="multiple-modules-defined-in-one-file">Multiple modules defined in one fi
175180
* @exports html/utils
176181
*/
177182
var utils = {
178-
/** Get the value of a property on an element. */
183+
/**
184+
* Get the value of a property on an element.
185+
* @param {HTMLElement} element - The element.
186+
* @param {string} propertyName - The name of the property.
187+
* @return {*} The value of the property.
188+
*/
179189
getStyleProperty: function(element, propertyName) { }
180190
};
181191

182-
/** Determine if an element is in the document head. */
192+
/**
193+
* Determine if an element is in the document head.
194+
* @param {HTMLElement} element - The element.
195+
* @return {boolean} Set to `true` if the element is in the document head,
196+
* `false` otherwise.
197+
*/
183198
utils.isInHead = function(element) { }
184199

185200
return utils;
@@ -190,7 +205,11 @@ <h2 id="multiple-modules-defined-in-one-file">Multiple modules defined in one fi
190205
define('tag', function() {
191206
/** @exports tag */
192207
var tag = {
193-
/** @class */
208+
/**
209+
* Create a new Tag.
210+
* @class
211+
* @param {string} tagName - The name of the tag.
212+
*/
194213
Tag: function(tagName) {
195214
// ...
196215
}

‎howto-commonjs-modules.html

Lines changed: 45 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -173,12 +173,22 @@ <h3 id="object-literal-assigned-to-module-exports-">Object literal assigned to &
173173
*/
174174

175175
module.exports = {
176-
/** Blend two colors together. */
176+
/**
177+
* Blend two colors together.
178+
* @param {string} color1 - The first color, in hexadecimal format.
179+
* @param {string} color2 - The second color, in hexadecimal format.
180+
* @return {string} The blended color.
181+
*/
177182
blend: function(color1, color2) {
178183
// ...
179184
},
180185

181-
/** Darken a color by the given percentage. */
186+
/**
187+
* Darken a color by the given percentage.
188+
* @param {string} color - The color, in hexadecimal format.
189+
* @param {number} percent - The percentage, ranging from 0 to 100.
190+
* @return {string} The darkened color.
191+
*/
182192
darken: function(color, percent) {
183193
// ..
184194
}
@@ -194,13 +204,23 @@ <h3 id="object-literal-assigned-to-module-exports-">Object literal assigned to &
194204
*/
195205

196206
module.exports = {
197-
/** Blend two colors together. */
207+
/**
208+
* Blend two colors together.
209+
* @param {string} color1 - The first color, in hexadecimal format.
210+
* @param {string} color2 - The second color, in hexadecimal format.
211+
* @return {string} The blended color.
212+
*/
198213
blend: function(color1, color2) {
199214
// ...
200215
}
201216
};
202217

203-
/** Darken a color by the given percentage. */
218+
/**
219+
* Darken a color by the given percentage.
220+
* @param {string} color - The color, in hexadecimal format.
221+
* @param {number} percent - The percentage, ranging from 0 to 100.
222+
* @return {string} The darkened color.
223+
*/
204224
module.exports.darken = function(color, percent) {
205225
// ..
206226
};
@@ -214,7 +234,12 @@ <h3 id="function-assigned-to-module-exports-">Function assigned to &#39;module.e
214234
* @module color/mixer
215235
*/
216236

217-
/** Blend two colors together. */
237+
/**
238+
* Blend two colors together.
239+
* @param {string} color1 - The first color, in hexadecimal format.
240+
* @param {string} color2 - The second color, in hexadecimal format.
241+
* @return {string} The blended color.
242+
*/
218243
module.exports = function(color1, color2) {
219244
// ...
220245
};
@@ -256,7 +281,12 @@ <h2 id="values-assigned-to-module-exports-and-local-variables">Values assigned t
256281
* @exports color/mixer
257282
*/
258283
var mixer = module.exports = {
259-
/** Blend two colors together. */
284+
/**
285+
* Blend two colors together.
286+
* @param {string} color1 - The first color, in hexadecimal format.
287+
* @param {string} color2 - The second color, in hexadecimal format.
288+
* @return {string} The blended color.
289+
*/
260290
blend: function(color1, color2) {
261291
// ...
262292
}
@@ -266,9 +296,16 @@ <h2 id="values-assigned-to-module-exports-and-local-variables">Values assigned t
266296
<h2 id="properties-added-to-this-">Properties added to &#39;this&#39;</h2>
267297
<p>When a module adds a property to its <code>this</code> object, JSDoc 3 automatically recognizes that the new property is exported by the module:</p>
268298
<figure>
269-
<figcaption>Properties added to a module&#39;s &#39;this&#39; object</figcaption><pre class="prettyprint lang-js"><code>/** @module bookshelf */
299+
<figcaption>Properties added to a module&#39;s &#39;this&#39; object</figcaption><pre class="prettyprint lang-js"><code>/**
300+
* Module for bookshelf-related utilities.
301+
* @module bookshelf
302+
*/
270303

271-
/** @class */
304+
/**
305+
* Create a new Book.
306+
* @class
307+
* @param {string} title - The title of the book.
308+
*/
272309
this.Book = function(title) {
273310
/** The title of the book. */
274311
this.title = title;

0 commit comments

Comments
 (0)