clean up access and public tag docs; don't say that setting access tag to public is a no-op (#106)

Author: hegemonic

content/en/tags-access.md

@@ -17,19 +17,32 @@ related:
 
 ## Overview
 
-The @access tag specifies the access level of a member. Note that "@access private" is the same as "@private", "@access protected" is the same as "@protected", and "@access public" is the same as "@public" which is the same as not including the tag at all. Private members will not show in the output documentation unless JSDoc is given the `--private` option.
+The `@access` tag specifies the access level of a member. You can use the `@access` tag as a
+synonym for other tags:
 
-Note that a doclet's _access level_ is different from its _scope_. For example, if "Parent" has an inner variable "child" that is documented as @public, "child" will still be treated as an inner variable with the namepath "Parent~child".
-To change a doclet's scope, see the [@instance][instance-tag], [@static][static-tag], and [@global][global-tag] tags.
++ `@access private` is the same as `@private`.
++ `@access protected` is the same as `@protected`.
++ `@access public` is the same as `@public`.
 
+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.
+
+Note that a doclet's _access level_ is different from its _scope_. For example, if `Parent` has an
+inner variable named `child` that is documented as `@public`, the `child` variable will still be
+treated as an inner variable with the namepath `Parent~child`. In other words, the `child` variable
+will have an inner scope, even though the variable is public. To change a doclet's scope, use the
+[`@instance`][instance-tag], [`@static`][static-tag], and [`@global`][global-tag] tags.
+
+[access-option]: about-commandline.html
 [global-tag]: tags-global.html
 [instance-tag]: tags-instance.html
 [static-tag]: tags-static.html
 
 
 ## Examples
 
-{% example "@access is a synonym for @private, @protected, @public." %}
+{% example "Using @access as a synonym for other tags" %}
 
 ```js
 /** @constructor */

content/en/tags-public.md

@@ -12,14 +12,14 @@ related:
 
 ## Overview
 
-The @public tag indicates that a symbol should be documented as if it were public.
+The `@public` tag indicates that a symbol should be documented as if it were public.
 
 By default, JSDoc treats all symbols as public, so using this tag does not normally affect the
-generated documentation. However, you may prefer to use the @public tag explicitly so it is clear to
-others that you intended to make the symbol public.
+generated documentation. However, you may prefer to use the `@public` tag explicitly so it is clear
+to others that you intended to make the symbol public.
 
-In contrast to previous version of JSDoc, the @public tag does _not_ affect a symbol's scope. Use
-the [@instance][instance-tag], [@static][static-tag], and [@global][global-tag] tags to change a
+In JSDoc 3, the `@public` tag does _not_ affect a symbol's scope. Use the
+[`@instance`][instance-tag], [`@static`][static-tag], and [`@global`][global-tag] tags to change a
 symbol's scope.
 
 [global-tag]: tags-global.html

tags-access.html

@@ -41,15 +41,21 @@ <h2 id="syntax">Syntax</h2>
     <p><code>@access &lt;private|protected|public&gt;</code>
     </p>
     <h2 id="overview">Overview</h2>
-    <p>The @access tag specifies the access level of a member. Note that &quot;@access private&quot; is the same as &quot;@private&quot;, &quot;@access protected&quot;
-      is the same as &quot;@protected&quot;, and &quot;@access public&quot; is the same as &quot;@public&quot; which is the same as not including the tag at all.
-      Private members will not show in the output documentation unless JSDoc is given the <code>--private</code> option.</p>
-    <p>Note that a doclet&#39;s <em>access level</em> is different from its <em>scope</em>. For example, if &quot;Parent&quot; has an inner variable &quot;child&quot;
-      that is documented as @public, &quot;child&quot; will still be treated as an inner variable with the namepath &quot;Parent~child&quot;. To change a doclet&#39;s
-      scope, see the <a href="tags-instance.html">@instance</a>, <a href="tags-static.html">@static</a>, and <a href="tags-global.html">@global</a> tags.</p>
+    <p>The <code>@access</code> tag specifies the access level of a member. You can use the <code>@access</code> tag as a synonym for other tags:</p>
+    <ul>
+      <li><code>@access private</code> is the same as <code>@private</code>.</li>
+      <li><code>@access protected</code> is the same as <code>@protected</code>.</li>
+      <li><code>@access public</code> is the same as <code>@public</code>.</li>
+    </ul>
+    <p>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>Note that a doclet&#39;s <em>access level</em> is different from its <em>scope</em>. For example, if <code>Parent</code> has an inner variable named <code>child</code>      that is documented as <code>@public</code>, the <code>child</code> variable will still be treated as an inner variable with the namepath <code>Parent~child</code>.
+      In other words, the <code>child</code> variable will have an inner scope, even though the variable is public. To change a doclet&#39;s scope, use the
+      <a href="tags-instance.html"><code>@instance</code></a>, <a href="tags-static.html"><code>@static</code></a>, and <a href="tags-global.html"><code>@global</code></a>      tags.</p>
     <h2 id="examples">Examples</h2>
     <figure>
-      <figcaption>@access is a synonym for @private, @protected, @public.</figcaption><pre class="prettyprint lang-js"><code>/** @constructor */
+      <figcaption>Using @access as a synonym for other tags</figcaption><pre class="prettyprint lang-js"><code>/** @constructor */
 function Thingy() {
 
     /** @access private */

tags-public.html

@@ -35,11 +35,10 @@ <h2>Table of Contents</h2>
       </li>
     </ul>
     <h2 id="overview">Overview</h2>
-    <p>The @public tag indicates that a symbol should be documented as if it were public.</p>
-    <p>By default, JSDoc treats all symbols as public, so using this tag does not normally affect the generated documentation. However, you may prefer to use the @public
-      tag explicitly so it is clear to others that you intended to make the symbol public.</p>
-    <p>In contrast to previous version of JSDoc, the @public tag does <em>not</em> affect a symbol&#39;s scope. Use the <a href="tags-instance.html">@instance</a>,
-      <a href="tags-static.html">@static</a>, and <a href="tags-global.html">@global</a> tags to change a symbol&#39;s scope.</p>
+    <p>The <code>@public</code> tag indicates that a symbol should be documented as if it were public.</p>
+    <p>By default, JSDoc treats all symbols as public, so using this tag does not normally affect the generated documentation. However, you may prefer to use the <code>@public</code>      tag explicitly so it is clear to others that you intended to make the symbol public.</p>
+    <p>In JSDoc 3, the <code>@public</code> tag does <em>not</em> affect a symbol&#39;s scope. Use the
+      <a href="tags-instance.html"><code>@instance</code></a>, <a href="tags-static.html"><code>@static</code></a>, and <a href="tags-global.html"><code>@global</code></a>      tags to change a symbol&#39;s scope.</p>
     <h2 id="examples">Examples</h2>
     <figure>
       <figcaption>Using the @public tag</figcaption><pre class="prettyprint lang-js"><code>/**