show how to document ES 2015 classes and modules (#110, #113)

Author: hegemonic

content/en/howto-amd-modules.md

@@ -3,6 +3,8 @@ title: AMD Modules
 description: How to add JSDoc comments to AMD and RequireJS modules.
 related:
     - about-namepaths.html
+    - tags-exports.html
+    - tags-module.html
 ---
 
 ## Overview

content/en/howto-commonjs-modules.md

@@ -3,6 +3,8 @@ title: CommonJS Modules
 description: How to add JSDoc comments to CommonJS and Node.js modules.
 related:
     - about-namepaths.html
+    - tags-exports.html
+    - tags-module.html
 ---
 
 ## Overview

content/en/howto-es2015-classes.md

@@ -0,0 +1,116 @@
+---
+title: ES 2015 Classes
+description: How to add JSDoc comments to ECMAScript 2015 classes.
+related:
+    - tags-augments.html
+---
+
+JSDoc 3 makes it easy to document classes that follow the [ECMAScript 2015
+specification][es2015-classes]. You don't need to use tags such as `@class` and `@constructor` with
+ES 2015 classes—JSDoc automatically identifies classes and their constructors simply by parsing your
+code. ES 2015 classes are supported in JSDoc 3.4.0 and later.
+
+[es2015-classes]: http://www.ecma-international.org/ecma-262/6.0/#sec-class-definitions
+
+
+## Documenting a simple class
+
+The following example shows how to document a simple class with a constructor, two instance methods,
+and one static method:
+
+{% example "Simple ES 2015 class" %}
+
+```js
+/** Class representing a point. */
+class Point {
+    /**
+     * Create a point.
+     * @param {number} x - The x value.
+     * @param {number} y - The y value.
+     */
+    constructor(x, y) {
+        // ...
+    }
+
+    /**
+     * Get the x value.
+     * @return {number} The x value.
+     */
+    getX() {
+        // ...
+    }
+
+    /**
+     * Get the y value.
+     * @return {number} The y value.
+     */
+    getY() {
+        // ...
+    }
+
+    /**
+     * Convert a string containing two comma-separated numbers into a point.
+     * @param {string} str - The string containing two comma-separated numbers.
+     * @return {Point} A Point object.
+     */
+    static fromString(str) {
+        // ...
+    }
+}
+```
+
+{% endexample %}
+
+You can also document classes that are defined in a class expression, which assigns the class to a
+variable or constant:
+
+{% example "ES 2015 class expression" %}
+
+```js
+/** Class representing a point. */
+const Point = class {
+    // and so on
+}
+```
+
+{% endexample %}
+
+
+## Extending classes
+
+When you use the `extends` keyword to extend an existing class, you also need to tell JSDoc which
+class you're extending. You do this with the [`@augments` (or `@extends`) tag][augments-tag].
+
+For example, to extend the `Point` class shown above:
+
+{% example "Extending an ES 2015 class" %}
+
+```js
+/**
+ * Class representing a dot.
+ * @extends Point
+ */
+class Dot extends Point {
+    /**
+     * Create a dot.
+     * @param {number} x - The x value.
+     * @param {number} y - The y value.
+     * @param {number} width - The width of the dot, in pixels.
+     */
+    constructor(x, y, width) {
+        // ...
+    }
+
+    /**
+     * Get the dot's width.
+     * @return {number} The dot's width, in pixels.
+     */
+    getWidth() {
+        // ...
+    }
+}
+```
+
+{% endexample %}
+
+[augments-tag]: tags-augments.html

content/en/howto-es2015-modules.md

@@ -0,0 +1,86 @@
+---
+title: ES 2015 Modules
+description: How to add JSDoc comments to ECMAScript 2015 modules.
+related:
+    - about-namepaths.html
+    - tags-module.html
+---
+
+JSDoc 3 makes it possible to document modules that follow the [ECMAScript 2015
+specification][es2015-modules]. ES 2015 modules are supported in JSDoc 3.4.0 and later.
+
+
+## Module identifiers
+
+When you document an ES 2015 module, you'll use a [`@module` tag][module-tag] to document the identifier for the module. For example, if users load the module by calling `import * as myShirt
+from 'my/shirt'`, you'll write a JSDoc comment that contains the tag `@module my/shirt`.
+
+If you use the `@module` tag without a value, JSDoc will try to guess the correct module identifier
+based on the filepath.
+
+When you use a JSDoc [namepath][namepaths] to refer to a module from another JSDoc comment, you must
+add the prefix `module:`. For example, if you want the documentation for the module `my/pants` to
+link to the module `my/shirt`, you could use the [`@see` tag][see-tag] to document `my/pants` as
+follows:
+
+```js
+/**
+ * Pants module.
+ * @module my/pants
+ * @see module:my/shirt
+ */
+```
+
+Similarly, the namepath for each member of the module will start with `module:`, followed by the
+module name. For example, if your `my/pants` module exports a `Jeans` class, and `Jeans` has an
+instance method named `hem`, the instance method's longname is `module:my/pants.Jeans#hem`.
+
+[module-tag]: tags-module.html
+[namepaths]: about-namepaths.html
+[see-tag]: tags-see.html
+
+
+## Exported values
+
+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 `export` statement that defines the
+exported value. If you are exporting a value under another name, you can document the exported value
+within its `export` block.
+
+{% example "Documenting values exported by a module" %}
+
+```js
+/** @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 hexidecimal format.
+ * @param {string} color2 - The second color, in hexidecimal 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 hexidecimal format.
+     * @returns {Array.<number>} An array of the red, green, and blue values,
+     * each ranging from 0 to 255.
+     */
+    rgbify as toRgb
+}
+```
+
+{% endexample %}
+
+[es2015-modules]: http://www.ecma-international.org/ecma-262/6.0/#sec-modules

data/toc.json

@@ -38,6 +38,12 @@
         }
     ],
     "examples": [
+        {
+            "filename": "howto-es2015-classes.html"
+        },
+        {
+            "filename": "howto-es2015-modules.html"
+        },
         {
             "filename": "howto-commonjs-modules.html"
         },

howto-amd-modules.html

@@ -201,9 +201,17 @@ <h2 id="multiple-modules-defined-in-one-file">Multiple modules defined in one fi
 </code></pre>
     </figure>
     <h2 id="related-links">Related Links</h2>
-    <p>
-      <a href="about-namepaths.html">Using namepaths with JSDoc 3</a>
-    </p>
+    <ul>
+      <li>
+        <a href="about-namepaths.html">Using namepaths with JSDoc 3</a>
+      </li>
+      <li>
+        <a href="tags-exports.html">@exports</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/">

howto-commonjs-modules.html

@@ -276,9 +276,17 @@ <h2 id="properties-added-to-this-">Properties added to &#39;this&#39;</h2>
 </code></pre>
     </figure>
     <h2 id="related-links">Related Links</h2>
-    <p>
-      <a href="about-namepaths.html">Using namepaths with JSDoc 3</a>
-    </p>
+    <ul>
+      <li>
+        <a href="about-namepaths.html">Using namepaths with JSDoc 3</a>
+      </li>
+      <li>
+        <a href="tags-exports.html">@exports</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/">