document config setting for tag dictionaries (#61)

Author: hegemonic

Diff for: about-configuring-jsdoc.html

@@ -38,11 +38,9 @@ <h2>Table of Contents</h2>
       </li>
       <li>
         <a href="#output-style-configuration">Output style configuration</a>
-        <ul>
-          <li>
-            <a href="#miscellaneous">Miscellaneous</a>
-          </li>
-        </ul>
+      </li>
+      <li>
+        <a href="#tags-and-tag-dictionaries">Tags and tag dictionaries</a>
       </li>
       <li>
         <a href="#related-links">Related Links</a>
@@ -54,7 +52,8 @@ <h2 id="configuration-file">Configuration File</h2>
       example. If you do not specify a configuration file, this is what JSDoc will use:</p>
     <figure><pre class="prettyprint lang-js"><code>{
     "tags": {
-        "allowUnknownTags": true
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
     },
     "source": {
         "includePattern": ".+\\.js(doc)?$",
@@ -70,6 +69,9 @@ <h2 id="configuration-file">Configuration File</h2>
     </figure>
     <p>This means:</p>
     <ul>
+      <li>JSDoc allows you to use unrecognized tags (<code>tags.allowUnknownTags</code>);</li>
+      <li>Both standard JSDoc tags and <a href="https://developers.google.com/closure/compiler/docs/js-for-compiler#tags">Closure Compiler tags</a> are enabled (
+        <code>tags.dictionaries</code>);</li>
       <li>Only files ending in &quot;.js&quot; and &quot;.jsdoc&quot; will be processed (<code>source.includePattern</code>);</li>
       <li>Any file starting with an underscore or in a directory starting with an underscore will be
         <em>ignored</em> (<code>source.excludePattern</code>);</li>
@@ -207,15 +209,28 @@ <h2 id="output-style-configuration">Output style configuration</h2>
       <code>{@link MyNamespace.myFunction}</code> will be in monospace.</p>
     <p>If <code>templates.cleverLinks</code> is true, it is used and <code>templates.monospaceLinks</code> is ignored.</p>
     <p>Also, there are {@linkcode ...} and {@linkplain ...} if one wishes to force the link to be rendered in monospace or normal font respectively (see <a href="tags-inline-link.html">@link, @linkcode and @linkplain</a>      for further information).</p>
-    <h3 id="miscellaneous">Miscellaneous</h3>
-    <p>The <code>tags.allowUnknownTags</code> property determines whether tags unrecognised by JSDoc are permitted. If this is false and JSDoc encounters a tag it does
-      not recognise (e.g. <code>@foobar</code>), it will throw an error. Otherwise, it will just ignore the tag.</p>
-    <p>By default, it is true.</p>
-    <figure><pre class="prettyprint"><code>"tags": {
-    "allowUnknownTags": true
+    <h2 id="tags-and-tag-dictionaries">Tags and tag dictionaries</h2>
+    <p>The options in <code>tags</code> control which JSDoc tags are allowed and how each tag is interpreted.</p>
+    <figure><pre class="prettyprint lang-js"><code>"tags": {
+    "allowUnknownTags": true,
+    "dictionaries": ["jsdoc","closure"]
 }
 </code></pre>
     </figure>
+    <p>The <code>tags.allowUnknownTags</code> property affects how JSDoc handles unrecognized tags. If you set this option to <code>false</code>, and JSDoc finds a
+      tag that it does not recognize (for example, <code>@foo</code>), JSDoc logs a warning. By default, this option is set to <code>true</code>.</p>
+    <p>The <code>tags.dictionaries</code> property controls which tags JSDoc recognizes, as well as how JSDoc interprets the tags that it recognizes. In JSDoc 3.3.0
+      and later, there are two built-in tag dictionaries:
+    </p>
+    <ul>
+      <li><code>jsdoc</code>: Core JSDoc tags.</li>
+      <li><code>closure</code>: <a href="https://developers.google.com/closure/compiler/docs/js-for-compiler#tags">Closure Compiler tags</a>.</li>
+    </ul>
+    <p>By default, both dictionaries are enabled. Also, by default, the <code>jsdoc</code> dictionary is listed first; as a result, if the <code>jsdoc</code> dictionary
+      handles a tag differently than the <code>closure</code> dictionary, the
+      <code>jsdoc</code> version of the tag takes precedence.</p>
+    <p>If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that Closure Compiler does not recognize, change the <code>tags.dictionaries</code>      setting to <code>[&quot;closure&quot;]</code>. You can also change this setting to <code>[&quot;closure&quot;,&quot;jsdoc&quot;]</code> if you want to allow
+      core JSDoc tags, but you want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would interpret them.</p>
     <h2 id="related-links">Related Links</h2>
     <ul>
       <li>

Diff for: content/en/about-configuring-jsdoc.md

@@ -20,7 +20,8 @@ file, this is what JSDoc will use:
 ```js
 {
     "tags": {
-        "allowUnknownTags": true
+        "allowUnknownTags": true,
+        "dictionaries": ["jsdoc","closure"]
     },
     "source": {
         "includePattern": ".+\\.js(doc)?$",
@@ -37,6 +38,9 @@ file, this is what JSDoc will use:
 
 This means:
 
++ JSDoc allows you to use unrecognized tags (`tags.allowUnknownTags`);
++ Both standard JSDoc tags and [Closure Compiler tags][closure-tags] are enabled
+(`tags.dictionaries`);
 + Only files ending in ".js" and ".jsdoc" will be processed (`source.includePattern`);
 + Any file starting with an underscore or in a directory starting with an underscore will be
 _ignored_ (`source.excludePattern`);
@@ -48,8 +52,10 @@ These options and others will be further explained on this page.
 Further settings may be added to the file as requested by various plugins or templates (for example,
 the [Markdown plugin][markdown] can be configured by including a "markdown" key).
 
+[closure-tags]: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags
 [markdown]: plugins-markdown.html
 
+
 ## Specifying input files
 
 The "source" set of options, in combination with paths given to JSDoc on the command-line, determine
@@ -152,6 +158,7 @@ The reasoning is as follows:
 3. Apply `source.excludePattern`, which will remove `myProject/_private/a.js`.
 4. Apply `source.exclude`, which will remove `myProject/lib/ignore.js`.
 
+
 ## Incorporating command-line options into the configuration file
 
 It is possible to put many of JSDoc's [command-line options][options] into the configuration file
@@ -242,19 +249,41 @@ further information).
 
 [link-tag]: tags-inline-link.html
 
-### Miscellaneous
 
-The `tags.allowUnknownTags` property determines whether tags unrecognised by JSDoc are permitted. If
-this is false and JSDoc encounters a tag it does not recognise (e.g. `@foobar`), it will throw an
-error. Otherwise, it will just ignore the tag.
+## Tags and tag dictionaries
+
+The options in `tags` control which JSDoc tags are allowed and how each tag is interpreted.
 
-By default, it is true.
 
 {% example %}
 
-```
+```js
 "tags": {
-    "allowUnknownTags": true
+    "allowUnknownTags": true,
+    "dictionaries": ["jsdoc","closure"]
 }
 ```
 {% endexample %}
+
+The `tags.allowUnknownTags` property affects how JSDoc handles unrecognized tags. If you set this
+option to `false`, and JSDoc finds a tag that it does not recognize (for example, `@foo`), JSDoc
+logs a warning. By default, this option is set to `true`.
+
+The `tags.dictionaries` property controls which tags JSDoc recognizes, as well as how JSDoc
+interprets the tags that it recognizes. In JSDoc 3.3.0 and later, there are two built-in tag
+dictionaries:
+
++ `jsdoc`: Core JSDoc tags.
++ `closure`: [Closure Compiler tags][closure-tags].
+
+By default, both dictionaries are enabled. Also, by default, the `jsdoc` dictionary is listed first;
+as a result, if the `jsdoc` dictionary handles a tag differently than the `closure` dictionary, the
+`jsdoc` version of the tag takes precedence.
+
+If you are using JSDoc with a Closure Compiler project, and you want to avoid using tags that
+Closure Compiler does not recognize, change the `tags.dictionaries` setting to `["closure"]`. You
+can also change this setting to `["closure","jsdoc"]` if you want to allow core JSDoc tags, but you
+want to ensure that Closure Compiler-specific tags are interpreted as Closure Compiler would
+interpret them.
+
+[closure-tags]: https://developers.google.com/closure/compiler/docs/js-for-compiler#tags