document ignore and license tags

hegemonic · hegemonic · commit f18ec01f322b · 2014-11-30T10:47:48.000-08:00
diff --git a/content/en/tags-ignore.md b/content/en/tags-ignore.md
@@ -1,18 +1,54 @@
 ---
 tag: ignore
-description: \[todo\] Remove this from the final output.
+description: Omit a symbol from the documentation.
 ---
 
 ## Overview
 
-TODO
+The `@ignore` tag indicates that a symbol in your code should never appear in the documentation. This tag takes precedence over all others.
+
+For most JSDoc templates, including the default template, the `@ignore` tag has the following effects:
+
++ If you use the `@ignore` tag with the `@class` or `@module` tag, the entire class or module will be omitted from the documentation.
++ If you use the `@ignore` tag with the `@namespace` tag, you must also add the `@ignore` tag to any child classes and namespaces. Otherwise, your documentation will show the child classes and namespaces, but with incomplete names.
 
 
 ## Examples
 
-{% example "Example goes here" %}
+In the following example, `Jacket` and `Jacket#color` will not appear in the documentation.
+
+{% example "Class with `@ignore` tag" %}
+
+```js
+/**
+ * @class
+ * @ignore
+ */
+function Jacket() {
+    /** The jacket's color. */
+    this.color = null;
+}
+```
+{% endexample %}
+
+In the following example, the `Clothes` namespace contains a `Jacket` class. The `@ignore` tag must be added to both `Clothes` and `Clothes.Jacket`. `Clothes`, `Clothes.Jacket`, and `Clothes.Jacket#color` will not appear in the documentation.
+
+{% example "Namespace with child class" %}
 
 ```js
-// todo
+/**
+ * @namespace
+ * @ignore
+ */
+var Clothes = {
+    /**
+     * @class
+     * @ignore
+     */
+    Jacket: function() {
+        /** The jacket's color. */
+        this.color = null;
+    }
+};
 ```
 {% endexample %}
diff --git a/content/en/tags-license.md b/content/en/tags-license.md
@@ -1,19 +1,29 @@
 ---
 tag: license
-description: \[todo\] Document the software license that applies to this code.
+description: Identify the license that applies to this code.
 ---
 
+## Syntax
+
+`@license <identifier>`
+
+
 ## Overview
 
-TODO
+The `@license` tag identifies the software license that applies to any portion of your code.
 
+You can use any text to identify the license you are using. If your code uses a standard open-source license, consider using the appropriate identifier from the [Software Package Data Exchange (SPDX) License List](https://spdx.org/licenses/).
 
-## Examples
 
+## Examples
 
-{% example "Example goes here" %}
+{% example "A module that is distributed under the Apache License 2.0" %}
 
 ```js
-// todo
+/**
+ * Utility functions for the foo package.
+ * @module foo/util
+ * @license Apache-2.0
+ */
 ```
 {% endexample %}
diff --git a/index.html b/index.html
@@ -108,7 +108,7 @@ <h2 id="tag-dictionary">Tag Dictionary</h2>
       <dt><a href="tags-global.html">@global</a></dt>
       <dd>Document a global object.</dd>
       <dt><a href="tags-ignore.html">@ignore</a></dt>
-      <dd>[todo] Remove this from the final output.</dd>
+      <dd>Omit a symbol from the documentation.</dd>
       <dt><a href="tags-inner.html">@inner</a></dt>
       <dd>Document an inner object.</dd>
       <dt><a href="tags-instance.html">@instance</a></dt>
@@ -118,7 +118,7 @@ <h2 id="tag-dictionary">Tag Dictionary</h2>
       <dt><a href="tags-lends.html">@lends</a></dt>
       <dd>Document properties on an object literal as if they belonged to a symbol with a given name.</dd>
       <dt><a href="tags-license.html">@license</a></dt>
-      <dd>[todo] Document the software license that applies to this code.</dd>
+      <dd>Identify the license that applies to this code.</dd>
       <dt><a href="tags-link.html">@link</a></dt>
       <dd>Inline tag - create a link.</dd>
       <dt><a href="tags-member.html">@member</a> (synonyms: @var)</dt>
diff --git a/tags-ignore.html b/tags-ignore.html
@@ -4,7 +4,7 @@
 
 <head>
   <meta charset="utf-8">
-  <meta name="description" content="[todo] Remove this from the final output.">
+  <meta name="description" content="Omit a symbol from the documentation.">
   <title>Use JSDoc: @ignore</title>
   <link rel="stylesheet" href="styles/usejsdoc.css">
   <link rel="stylesheet" href="styles/prettify.css">
@@ -32,10 +32,42 @@ <h2>Table of Contents</h2>
       </li>
     </ul>
     <h2 id="overview">Overview</h2>
-    <p>TODO</p>
+    <p>The <code>@ignore</code> tag indicates that a symbol in your code should never appear in the documentation. This tag takes precedence over all others.</p>
+    <p>For most JSDoc templates, including the default template, the <code>@ignore</code> tag has the following effects:</p>
+    <ul>
+      <li>If you use the <code>@ignore</code> tag with the <code>@class</code> or <code>@module</code> tag, the entire class or module will be omitted from the documentation.</li>
+      <li>If you use the <code>@ignore</code> tag with the <code>@namespace</code> tag, you must also add the <code>@ignore</code> tag to any child classes and namespaces.
+        Otherwise, your documentation will show the child classes and namespaces, but with incomplete names.</li>
+    </ul>
     <h2 id="examples">Examples</h2>
+    <p>In the following example, <code>Jacket</code> and <code>Jacket#color</code> will not appear in the documentation.</p>
+    <figure>
+      <figcaption>Class with <code>@ignore</code> tag</figcaption><pre class="prettyprint lang-js"><code>/**
+ * @class
+ * @ignore
+ */
+function Jacket() {
+    /** The jacket's color. */
+    this.color = null;
+}
+</code></pre>
+    </figure>
+    <p>In the following example, the <code>Clothes</code> namespace contains a <code>Jacket</code> class. The <code>@ignore</code> tag must be added to both <code>Clothes</code>      and <code>Clothes.Jacket</code>. <code>Clothes</code>, <code>Clothes.Jacket</code>, and <code>Clothes.Jacket#color</code> will not appear in the documentation.</p>
     <figure>
-      <figcaption>Example goes here</figcaption><pre class="prettyprint lang-js"><code>// todo
+      <figcaption>Namespace with child class</figcaption><pre class="prettyprint lang-js"><code>/**
+ * @namespace
+ * @ignore
+ */
+var Clothes = {
+    /**
+     * @class
+     * @ignore
+     */
+    Jacket: function() {
+        /** The jacket's color. */
+        this.color = null;
+    }
+};
 </code></pre>
     </figure>
   </article>
diff --git a/tags-license.html b/tags-license.html
@@ -4,7 +4,7 @@
 
 <head>
   <meta charset="utf-8">
-  <meta name="description" content="[todo] Document the software license that applies to this code.">
+  <meta name="description" content="Identify the license that applies to this code.">
   <title>Use JSDoc: @license</title>
   <link rel="stylesheet" href="styles/usejsdoc.css">
   <link rel="stylesheet" href="styles/prettify.css">
@@ -24,18 +24,30 @@
     <h1>@license</h1>
     <h2>Table of Contents</h2>
     <ul>
+      <li>
+        <a href="#syntax">Syntax</a>
+      </li>
       <li>
         <a href="#overview">Overview</a>
       </li>
       <li>
         <a href="#examples">Examples</a>
       </li>
     </ul>
+    <h2 id="syntax">Syntax</h2>
+    <p><code>@license &lt;identifier&gt;</code>
+    </p>
     <h2 id="overview">Overview</h2>
-    <p>TODO</p>
+    <p>The <code>@license</code> tag identifies the software license that applies to any portion of your code.</p>
+    <p>You can use any text to identify the license you are using. If your code uses a standard open-source license, consider using the appropriate identifier from
+      the <a href="https://spdx.org/licenses/">Software Package Data Exchange (SPDX) License List</a>.</p>
     <h2 id="examples">Examples</h2>
     <figure>
-      <figcaption>Example goes here</figcaption><pre class="prettyprint lang-js"><code>// todo
+      <figcaption>A module that is distributed under the Apache License 2.0</figcaption><pre class="prettyprint lang-js"><code>/**
+ * Utility functions for the foo package.
+ * @module foo/util
+ * @license Apache-2.0
+ */
 </code></pre>
     </figure>
   </article>
