document Closure syntax for private and protected tags (#62)

Author: hegemonic

Diff for: content/en/tags-private.md

@@ -3,26 +3,38 @@ tag: private
 description: This symbol is meant to be private.
 related:
     - tags-access.html
+    - tags-global.html
     - tags-instance.html
     - tags-protected.html
     - tags-public.html
     - tags-static.html
-    - tags-global.html
 ---
 
+## Syntax
+
+With the JSDoc tag dictionary (enabled by default):
+
+`@private`
+
+With the [Closure Compiler] tag dictionary:
+
+`@private [{typeExpression}]`
+
+
 ## Overview
 
-The @private tag marks a symbol as private, or not meant for general use. Private members are not
-shown in the generated output unless JSDoc is run with the `-p` or `--private` switch.
+The `@private` tag marks a symbol as private, or not meant for general use. Private members are not
+shown in the generated output unless JSDoc is run with the `-p/--private` command-line option. In
+JSDoc 3.3.0 and later, you can also use the [`-a/--access` command-line option][access-option] to
+change this behavior.
 
-The @private tag is not inherited by child members. For example, if the @private tag is added to a
-namespace, members of the namespace can still appear in the generated output; because the namespace
-is private, the members' namepath will not include the namespace.
+The `@private` tag is not inherited by child members. For example, if the `@private` tag is added to
+a namespace, members of the namespace can still appear in the generated output; because the
+namespace is private, the members' namepath will not include the namespace.
 
-The @private tag is equivalent to "@access private". See [@access][access-tag] for details about the
-@access tag.
+The `@private` tag is equivalent to `@access private`.
 
-[access-tag]: tags-access.html
+[access-option]: about-commandline.html
 
 
 ## Examples

Diff for: content/en/tags-protected.md

@@ -1,6 +1,6 @@
 ---
 tag: protected
-description: This member is meant to be protected.
+description: This symbol is meant to be protected.
 related:
     - tags-access.html
     - tags-global.html
@@ -10,17 +10,36 @@ related:
     - tags-static.html
 ---
 
+## Syntax
+
+With the JSDoc tag dictionary (enabled by default):
+
+`@protected`
+
+With the [Closure Compiler] tag dictionary:
+
+`@protected [{typeExpression}]`
+
+
 ## Overview
 
-This tag marks a doclet as protected.
+The `@protected` tag marks a symbol as protected. Typically, this tag indicates that a symbol is
+only available, or should only be used, within the current module.
 
-Note that "@protected" is equivalent to "@access protected". See [@access][access-tag] for details.
+By default, symbols marked with the `@protected` tag will appear in your documentation. In JSDoc
+3.3.0 and later, you can use the [`-a/--access` command-line option][access-option] to change this
+behavior.
 
-[access-tag]: tags-access.html
+The `@protected` tag is equivalent to `@access protected`.
+
+[access-option]: about-commandline.html
 
 
 ## Examples
 
+In the following example, the instance member `Thingy#_bar` appears in the generated documentation,
+but with an annotation indicating that it is protected:
+
 {% example "Using the @protected tag" %}
 
 ```js

Diff for: index.html

@@ -143,7 +143,7 @@ <h2 id="block-tags">Block Tags</h2>
       <dt><a href="tags-property.html">@property</a> (synonyms: @prop)</dt>
       <dd>Document a property of an object.</dd>
       <dt><a href="tags-protected.html">@protected</a></dt>
-      <dd>This member is meant to be protected.</dd>
+      <dd>This symbol is meant to be protected.</dd>
       <dt><a href="tags-public.html">@public</a></dt>
       <dd>This symbol is meant to be public.</dd>
       <dt><a href="tags-readonly.html">@readonly</a></dt>

Diff for: tags-private.html

@@ -24,6 +24,9 @@
     <h1>@private</h1>
     <h2>Table of Contents</h2>
     <ul>
+      <li>
+        <a href="#syntax">Syntax</a>
+      </li>
       <li>
         <a href="#overview">Overview</a>
       </li>
@@ -34,12 +37,19 @@ <h2>Table of Contents</h2>
         <a href="#related-links">Related Links</a>
       </li>
     </ul>
+    <h2 id="syntax">Syntax</h2>
+    <p>With the JSDoc tag dictionary (enabled by default):</p>
+    <p><code>@private</code>
+    </p>
+    <p>With the [Closure Compiler] tag dictionary:</p>
+    <p><code>@private [{typeExpression}]</code>
+    </p>
     <h2 id="overview">Overview</h2>
-    <p>The @private tag marks a symbol as private, or not meant for general use. Private members are not shown in the generated output unless JSDoc is run with the
-      <code>-p</code> or <code>--private</code> switch.</p>
-    <p>The @private tag is not inherited by child members. For example, if the @private tag is added to a namespace, members of the namespace can still appear in the
-      generated output; because the namespace is private, the members&#39; namepath will not include the namespace.</p>
-    <p>The @private tag is equivalent to &quot;@access private&quot;. See <a href="tags-access.html">@access</a> for details about the @access tag.</p>
+    <p>The <code>@private</code> tag marks a symbol as private, or not meant for general use. Private members are not shown in the generated output unless JSDoc is
+      run with the <code>-p/--private</code> command-line option. In JSDoc 3.3.0 and later, you can also use the <a href="about-commandline.html"><code>-a/--access</code> command-line option</a>      to change this behavior.</p>
+    <p>The <code>@private</code> tag is not inherited by child members. For example, if the <code>@private</code> tag is added to a namespace, members of the namespace
+      can still appear in the generated output; because the namespace is private, the members&#39; namepath will not include the namespace.</p>
+    <p>The <code>@private</code> tag is equivalent to <code>@access private</code>.</p>
     <h2 id="examples">Examples</h2>
     <p>In the following example, <code>Documents</code> and <code>Documents.Newspaper</code> appear in the generated documentation, but not <code>Documents.Diary</code>.</p>
     <figure>
@@ -62,6 +72,9 @@ <h2 id="related-links">Related Links</h2>
       <li>
         <a href="tags-access.html">@access</a>
       </li>
+      <li>
+        <a href="tags-global.html">@global</a>
+      </li>
       <li>
         <a href="tags-instance.html">@instance</a>
       </li>
@@ -74,9 +87,6 @@ <h2 id="related-links">Related Links</h2>
       <li>
         <a href="tags-static.html">@static</a>
       </li>
-      <li>
-        <a href="tags-global.html">@global</a>
-      </li>
     </ul>
   </article>
   <footer>

Diff for: tags-protected.html

@@ -4,7 +4,7 @@
 
 <head>
   <meta charset="utf-8">
-  <meta name="description" content="This member is meant to be protected.">
+  <meta name="description" content="This symbol is meant to be protected.">
   <title>Use JSDoc: @protected</title>
   <link rel="stylesheet" href="styles/usejsdoc.css">
   <link rel="stylesheet" href="styles/prettify.css">
@@ -24,6 +24,9 @@
     <h1>@protected</h1>
     <h2>Table of Contents</h2>
     <ul>
+      <li>
+        <a href="#syntax">Syntax</a>
+      </li>
       <li>
         <a href="#overview">Overview</a>
       </li>
@@ -34,10 +37,21 @@ <h2>Table of Contents</h2>
         <a href="#related-links">Related Links</a>
       </li>
     </ul>
+    <h2 id="syntax">Syntax</h2>
+    <p>With the JSDoc tag dictionary (enabled by default):</p>
+    <p><code>@protected</code>
+    </p>
+    <p>With the [Closure Compiler] tag dictionary:</p>
+    <p><code>@protected [{typeExpression}]</code>
+    </p>
     <h2 id="overview">Overview</h2>
-    <p>This tag marks a doclet as protected.</p>
-    <p>Note that &quot;@protected&quot; is equivalent to &quot;@access protected&quot;. See <a href="tags-access.html">@access</a> for details.</p>
+    <p>The <code>@protected</code> tag marks a symbol as protected. Typically, this tag indicates that a symbol is only available, or should only be used, within the
+      current module.</p>
+    <p>By default, symbols marked with the <code>@protected</code> tag will appear in your documentation. In JSDoc 3.3.0 and later, you can use the <a href="about-commandline.html"><code>-a/--access</code> command-line option</a>      to change this behavior.
+    </p>
+    <p>The <code>@protected</code> tag is equivalent to <code>@access protected</code>.</p>
     <h2 id="examples">Examples</h2>
+    <p>In the following example, the instance member <code>Thingy#_bar</code> appears in the generated documentation, but with an annotation indicating that it is protected:</p>
     <figure>
       <figcaption>Using the @protected tag</figcaption><pre class="prettyprint lang-js"><code>/** @constructor */
 function Thingy() {