Skip to content

Commit 215bb84

Browse files
mathematicalcoffeemathematicalcoffee
committed
filled out @module page
1 parent e486be0 commit 215bb84

File tree

3 files changed

+138
-17
lines changed

3 files changed

+138
-17
lines changed

‎Jake/articles/tags-module

Lines changed: 60 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,77 @@
11
<!--{
22
"title": "@module",
33
"out": "tags-module.html",
4-
"description": "[todo] Document a JavaScript module."
4+
"description": "Document a JavaScript module."
55
}-->
6+
<h3>Syntax</h3>
7+
<code>@module [&lt;ModuleName&gt;]</code>
8+
69
<h3>Overview</h3>
710

8-
<p>
11+
<p>This marks the current file as being its own module.
12+
All symbols in the file are members of the module (unless documented otherwise, see (e.g.) <a href="tags-memberof.html">@memberof</a>).
13+
</p>
14+
15+
<p>Link to a module (e.g. within a <a href="tags-link.html">@link</a> or <a href="tags-see.html">@see</a>) using "module:moduleName". For example, "@module foo/bar" can be linked to using "{@link module:foo/bar}".
16+
</p>
17+
18+
<p>If the module name is not provided, it is set to the current filename relative to the folder JSDoc is run on.
19+
</p>
20+
21+
<p>For example, suppose I have a file <code>test.js</code> with doclet <code>/** @module */</code> in it, in folder 'src'.
22+
Here are some scenarios for running JSDoc and the resulting module names for test.js:
923
</p>
1024

25+
{{#example}}Derived module names if none is provided.
26+
# from src/
27+
jsdoc ./test.js # module name 'test'
28+
29+
# from src's parent directory:
30+
jsdoc src/test.js # module name 'src/test'
31+
jsdoc -r src/ # module name 'test'
32+
{{/example}}
33+
1134
<h3>Examples</h3>
35+
{{#example}}Basic @module use.
36+
/** @module myModule */
37+
38+
/** will be module:myMmodule~foo */
39+
var foo = 1;
40+
{{/example}}
1241

13-
<p>
42+
There are many ways to export objects as belonging to a module (i.e. as static members rather than inner as in the example above). These include assigning the objects to <code>module.exports</code> or <code>exports</code> or <code>this</code>.
43+
44+
{{#example}}Using 'this' in a file with @module.
45+
/** @module bookshelf */
46+
/** @class */
47+
this.Book = function (title) {
48+
/** The title. */
49+
this.title = title;
50+
};
51+
{{/example}}
52+
<p>When a global symbol is a member of 'this' in a file with a @module tag, the symbol is documented as a member of that module.
53+
So the Book class above is documented as <code>module:bookshelf.Book</code>. The title is <code>module:bookshelf.Book#title</code> as expected.
1454
</p>
1555

16-
{{#example}}Example goes here
17-
// todo
56+
{{#example}}Documenting under a namespace 'module.exports' or 'exports'.
57+
/** @module color/mixer */
58+
module.exports = {
59+
/** Blend two colours together. */
60+
blend: function (color1, color2) {}
61+
};
62+
/** Darkens a color. */
63+
exports.darken = function (color, shade) {};
1864
{{/example}}
65+
<p>JSDoc recognises assigning to <code>module.exports</code> or <code>exports</code> as assigning to the module.
66+
Hence the two functions above will have names "module:color/mixer.blend" and "module:color/mixer.darken".
67+
</p>
68+
69+
See <a href="howto-commonjs-modules.html">Documenting Javascript Modules</a> for further examples of using @module as a constructor, or documenting multiple modules in a file.
1970

2071
<h3>See Also</h3>
2172

2273
<ul>
23-
<li><a href="#">...</a></li>
24-
</ul>
74+
<li><a href="howto-commonjs-modules.html">Other helpful @module examples</a></li>
75+
<li><a href="tags-exports.html">@exports</a></li>
76+
<li><a href="tags-namespace.html">@namespace</a></li>
77+
</ul>

‎index.html

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -271,7 +271,7 @@ <h2 name="JSDoc3_Tag_Dictionary" id="JSDoc3_Tag_Dictionary">JSDoc 3 Tag Dictiona
271271
<dd>[todo] Document the software license that applies to this code.</dd> <dt><a href="tags-fires.html">@fires</a></dt>
272272
<dd>Describe the events this method may fire.</dd> <dt><a href="tags-callback.html">@callback</a></dt>
273273
<dd>Document a callback function.</dd> <dt><a href="tags-module.html">@module</a></dt>
274-
<dd>[todo] Document a JavaScript module.</dd> <dt><a href="tags-protected.html">@protected</a></dt>
274+
<dd>Document a JavaScript module.</dd> <dt><a href="tags-protected.html">@protected</a></dt>
275275
<dd>This member is meant to be protected.</dd> <dt><a href="tags-typedef.html">@typedef</a></dt>
276276
<dd>Document a custom type.</dd> <dt><a href="tags-global.html">@global</a></dt>
277277
<dd>Document a global object.</dd> <dt><a href="tags-public.html">@public</a></dt>

‎tags-module.html

Lines changed: 77 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
<html lang="en">
33
<head>
44
<meta charset="utf-8">
5-
<meta name="description" content="[todo] Document a JavaScript module."><title>Use JSDoc: @module</title>
5+
<meta name="description" content="Document a JavaScript module."><title>Use JSDoc: @module</title>
66

77
<link rel="stylesheet" href="lib/prettify.css" />
88
<script src="lib/prettify.js"></script>
@@ -176,29 +176,97 @@
176176
<article>
177177
<h1>@module</h1>
178178

179+
<h3>Syntax</h3>
180+
<code>@module [&lt;ModuleName&gt;]</code>
181+
179182
<h3>Overview</h3>
180183

181-
<p>
184+
<p>This marks the current file as being its own module.
185+
All symbols in the file are members of the module (unless documented otherwise, see (e.g.) <a href="tags-memberof.html">@memberof</a>).
186+
</p>
187+
188+
<p>Link to a module (e.g. within a <a href="tags-link.html">@link</a> or <a href="tags-see.html">@see</a>) using "module:moduleName". For example, "@module foo/bar" can be linked to using "{@link module:foo/bar}".
182189
</p>
183190

184-
<h3>Examples</h3>
191+
<p>If the module name is not provided, it is set to the current filename relative to the folder JSDoc is run on.
192+
</p>
185193

186-
<p>
194+
<p>For example, suppose I have a file <code>test.js</code> with doclet <code>/** @module */</code> in it, in folder 'src'.
195+
Here are some scenarios for running JSDoc and the resulting module names for test.js:
187196
</p>
188197

189198
<dl class="example">
190-
<dt>Example goes here</dt>
199+
<dt>Derived module names if none is provided.</dt>
200+
<dd>
201+
<pre class="prettyprint lang-js">
202+
# from src/
203+
jsdoc ./test.js # module name 'test'
204+
205+
# from src's parent directory:
206+
jsdoc src/test.js # module name 'src/test'
207+
jsdoc -r src/ # module name 'test'
208+
209+
</pre>
210+
</dd>
211+
</dl><h3>Examples</h3>
212+
<dl class="example">
213+
<dt>Basic @module use.</dt>
191214
<dd>
192215
<pre class="prettyprint lang-js">
193-
// todo
216+
/** @module myModule */
217+
218+
/** will be module:myMmodule~foo */
219+
var foo = 1;
194220

195221
</pre>
196222
</dd>
197-
</dl><h3>See Also</h3>
223+
</dl>There are many ways to export objects as belonging to a module (i.e. as static members rather than inner as in the example above). These include assigning the objects to <code>module.exports</code> or <code>exports</code> or <code>this</code>.
224+
225+
<dl class="example">
226+
<dt>Using &#39;this&#39; in a file with @module.</dt>
227+
<dd>
228+
<pre class="prettyprint lang-js">
229+
/** @module bookshelf */
230+
/** @class */
231+
this.Book = function (title) {
232+
/** The title. */
233+
this.title = title;
234+
};
235+
236+
</pre>
237+
</dd>
238+
</dl><p>When a global symbol is a member of 'this' in a file with a @module tag, the symbol is documented as a member of that module.
239+
So the Book class above is documented as <code>module:bookshelf.Book</code>. The title is <code>module:bookshelf.Book#title</code> as expected.
240+
</p>
241+
242+
<dl class="example">
243+
<dt>Documenting under a namespace &#39;module.exports&#39; or &#39;exports&#39;.</dt>
244+
<dd>
245+
<pre class="prettyprint lang-js">
246+
/** @module color/mixer */
247+
module.exports = {
248+
/** Blend two colours together. */
249+
blend: function (color1, color2) {}
250+
};
251+
/** Darkens a color. */
252+
exports.darken = function (color, shade) {};
253+
254+
</pre>
255+
</dd>
256+
</dl><p>JSDoc recognises assigning to <code>module.exports</code> or <code>exports</code> as assigning to the module.
257+
Hence the two functions above will have names "module:color/mixer.blend" and "module:color/mixer.darken".
258+
</p>
259+
260+
See <a href="howto-commonjs-modules.html">Documenting Javascript Modules</a> for further examples of using @module as a constructor, or documenting multiple modules in a file.
261+
262+
<h3>See Also</h3>
198263

199264
<ul>
200-
<li><a href="#">...</a></li>
201-
</ul>
265+
<li><a href="howto-commonjs-modules.html">Other helpful @module examples</a></li>
266+
<li><a href="tags-exports.html">@exports</a></li>
267+
<li><a href="tags-namespace.html">@namespace</a></li>
268+
</ul>
269+
202270
</article>
203271

204272
<footer>

0 commit comments

Comments
 (0)