From 34d98ed438d33afa7e1bd8bdb6e69221111c1936 Mon Sep 17 00:00:00 2001
From: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Sun, 16 Feb 2014 08:39:32 -0800
Subject: [PATCH] add `@also` to tag definitions (#574)

This tag is used internally. It previously caused
"not a known tag" errors when
tags.allowUnknownTags was set to false.
---
 lib/jsdoc/tag/dictionary/definitions.js | 18 ++++++++++++++++++
 test/specs/documentation/also.js        | 24 +++++++++++++++++++++++-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/lib/jsdoc/tag/dictionary/definitions.js b/lib/jsdoc/tag/dictionary/definitions.js
index 04a210a3..2882612c 100644
--- a/lib/jsdoc/tag/dictionary/definitions.js
+++ b/lib/jsdoc/tag/dictionary/definitions.js
@@ -164,6 +164,24 @@ exports.defineTags = function(dictionary) {
             doclet.alias = tag.value;
         }
     });
+
+    // Special separator tag indicating that multiple doclets should be generated for the same
+    // comment. Used internally (and by some JSDoc users, although it's not officially supported).
+    //
+    // In the following example, the parser will replace `//**` with an `@also` tag:
+    //
+    // /**
+    //  * Foo.
+    //  *//**
+    //  * Foo with a param.
+    //  * @param {string} bar
+    //  */
+    //  function foo(bar) {}
+    dictionary.defineTag('also', {
+        onTagged: function(doclet, tag) {
+            // let the parser handle it; we define the tag here to avoid "not a known tag" errors
+        }
+    });
     
     // this symbol inherits from the specified symbol
     dictionary.defineTag('augments', {
diff --git a/test/specs/documentation/also.js b/test/specs/documentation/also.js
index ca71151a..5afc5783 100644
--- a/test/specs/documentation/also.js
+++ b/test/specs/documentation/also.js
@@ -1,4 +1,4 @@
-/*global describe: true, expect: true, it: true, jasmine: true */
+/*global describe, expect, it, jasmine, spyOn */
 describe("multiple doclets per symbol", function() {
     function undocumented($) {
         return ! $.undocumented;
@@ -44,4 +44,26 @@ describe("multiple doclets per symbol", function() {
         checkInequality(name, 'returns.length');
         checkInequality(shape, 'returns.length');
     });
+
+    it('When a file contains a JSDoc comment with an @also tag, and the "tags.allowUnknownTags" ' +
+        'option is set to false, the file can be parsed without errors.', function() {
+        var logger = require('jsdoc/util/logger');
+
+        var allowUnknownTags = !!global.env.conf.tags.allowUnknownTags;
+        var docs;
+        var errors = [];
+
+        function errorListener(err) {
+            errors.push(err);
+        }
+
+        logger.addListener('logger:error', errorListener);
+        global.env.conf.tags.allowUnknownTags = false;
+
+        docs = jasmine.getDocSetFromFile('test/fixtures/also2.js');
+        expect(errors[0]).not.toBeDefined();
+
+        logger.removeListener('logger:error', errorListener);
+        global.env.conf.tags.allowUnknownTags = allowUnknownTags;
+    });
 });