forked from jsdoc/jsdoc.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
howto-es2015-modules.html
119 lines (111 loc) · 4.87 KB
/
howto-es2015-modules.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
<!DOCTYPE html>
<!-- THIS IS A GENERATED FILE. DO NOT EDIT. -->
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="description" content="How to add JSDoc comments to ECMAScript 2015 modules.">
<title>Use JSDoc: ES 2015 Modules</title>
<link rel="stylesheet" href="styles/usejsdoc.css">
<link rel="stylesheet" href="styles/prettify.css">
<link rel="stylesheet" href="styles/css3-github-ribbon.css">
<script src="scripts/prettify.js"></script>
</head>
<body>
<header>
<a href="./index.html">@use JSDoc</a>
</header>
<article>
<h1>ES 2015 Modules</h1>
<h2>Table of Contents</h2>
<ul>
<li>
<a href="#module-identifiers">Module identifiers</a>
</li>
<li>
<a href="#exported-values">Exported values</a>
</li>
<li>
<a href="#related-links">Related Links</a>
</li>
</ul>
<p>JSDoc 3 makes it possible to document modules that follow the <a href="http://www.ecma-international.org/ecma-262/6.0/#sec-modules">ECMAScript 2015
specification</a>. ES 2015 modules are supported in JSDoc 3.4.0 and later.</p>
<h2 id="module-identifiers">Module identifiers</h2>
<p>When you document an ES 2015 module, you'll use a <a href="tags-module.html"><code>@module</code> tag</a> to document the
identifier for the module. For example, if users load the module by calling <code>import * as myShirt
from 'my/shirt'</code>, you'll write a JSDoc comment that contains the tag <code>@module my/shirt</code>.</p>
<p>If you use the <code>@module</code> tag without a value, JSDoc will try to guess the correct module identifier
based on the filepath.</p>
<p>When you use a JSDoc <a href="about-namepaths.html">namepath</a> to refer to a module from another JSDoc comment, you must
add the prefix <code>module:</code>. For example, if you want the documentation for the module <code>my/pants</code> to
link to the module <code>my/shirt</code>, you could use the <a href="tags-see.html"><code>@see</code> tag</a> to document <code>my/pants</code> as
follows:</p>
<pre class="prettyprint lang-js"><code>/**
* Pants module.
* @module my/pants
* @see module:my/shirt
*/
</code></pre>
<p>Similarly, the namepath for each member of the module will start with <code>module:</code>, followed by the
module name. For example, if your <code>my/pants</code> module exports a <code>Jeans</code> class, and <code>Jeans</code> has an
instance method named <code>hem</code>, the instance method's longname is <code>module:my/pants.Jeans#hem</code>.</p>
<h2 id="exported-values">Exported values</h2>
<p>The following example shows how to document different kinds of exported values in an ES 2015 module.
In most cases, you can simply add a JSDoc comment to the <code>export</code> statement that defines the
exported value. If you are exporting a value under another name, you can document the exported value
within its <code>export</code> block.</p>
<figure>
<figcaption>Documenting values exported by a module</figcaption>
<pre class="prettyprint lang-js"><code>/** @module color/mixer */
/** The name of the module. */
export const name = 'mixer';
/** The most recent blended color. */
export var lastColor = null;
/**
* Blend two colors together.
* @param {string} color1 - The first color, in hexadecimal format.
* @param {string} color2 - The second color, in hexadecimal format.
* @return {string} The blended color.
*/
export function blend(color1, color2) {}
// convert color to array of RGB values (0-255)
function rgbify(color) {}
export {
/**
* Get the red, green, and blue values of a color.
* @function
* @param {string} color - A color, in hexadecimal format.
* @returns {Array.<number>} An array of the red, green, and blue values,
* each ranging from 0 to 255.
*/
rgbify as toRgb
}
</code></pre>
</figure>
<h2 id="related-links">Related Links</h2>
<ul>
<li>
<a href="about-namepaths.html">Using namepaths with JSDoc 3</a>
</li>
<li>
<a href="tags-module.html">@module</a>
</li>
</ul>
</article>
<footer>
<a class="license-badge" href="http://creativecommons.org/licenses/by-sa/3.0/">
<img alt="Creative Commons License" class="license-badge" src="images/cc-by-sa.svg" width="80" height="15" /></a>
<br>
Copyright © 2011-2017 the
<a href="https://github.com/jsdoc3/jsdoc3.github.com/contributors">contributors</a> to the
JSDoc 3 documentation project.
<br>
This website is <a href="https://github.com/jsdoc3/jsdoc3.github.com">open source</a> and is
licensed under the <a rel="license" href="http://creativecommons.org/licenses/by-sa/3.0/">
Creative Commons Attribution-ShareAlike 3.0 Unported License</a>.
</footer>
<script type="text/javascript">
prettyPrint();
</script>
</body>
</html>