support virtual comments for overloaded symbols (#727)

lib/jsdoc/schema.js

@@ -629,7 +629,6 @@ var PACKAGE_SCHEMA = exports.PACKAGE_SCHEMA = {
 
 var DOCLETS_SCHEMA = exports.DOCLETS_SCHEMA = {
     type: ARRAY,
-    uniqueItems: true,
     items: {
         anyOf: [DOCLET_SCHEMA, PACKAGE_SCHEMA]
     }

lib/jsdoc/src/handlers.js

@@ -202,27 +202,36 @@ exports.attachTo = function(parser) {
         e.doclet = newDoclet;
     }
 
-    // handles JSDoc comments that include a @name tag -- the code is ignored in such a case
+    // Handle JSDoc "virtual comments" that include one of the following:
+    //
+    // + A `@name` tag
+    // + Another tag that accepts a name, such as `@function`
     parser.on('jsdocCommentFound', function(e) {
-        var newDoclet = getNewDoclet(e.comment, e);
+        var comments = e.comment.split(/@also\b/g);
+        var newDoclet;
 
-        if (!newDoclet.name) {
-            return false; // only interested in virtual comments (with a @name) here
+        for (var i = 0, l = comments.length; i < l; i++) {
+            newDoclet = getNewDoclet(comments[i], e);
+
+            // we're only interested in virtual comments here
+            if (!newDoclet.name) {
+                continue;
+            }
+
+            setDefaultScopeMemberOf(newDoclet);
+            newDoclet.postProcess();
+            addDoclet.call(parser, newDoclet);
+
+            e.doclet = newDoclet;
         }
-
-        setDefaultScopeMemberOf(newDoclet);
-        newDoclet.postProcess();
-        addDoclet.call(parser, newDoclet);
-
-        e.doclet = newDoclet;
     });
 
-    // handles named symbols in the code, may or may not have a JSDoc comment attached
+    // Handle named symbols in the code. May or may not have a JSDoc comment attached.
     parser.on('symbolFound', function(e) {
-        var subDoclets = e.comment.split(/@also\b/g);
+        var comments = e.comment.split(/@also\b/g);
 
-        for (var i = 0, l = subDoclets.length; i < l; i++) {
-            newSymbolDoclet.call(parser, subDoclets[i], e);
+        for (var i = 0, l = comments.length; i < l; i++) {
+            newSymbolDoclet.call(parser, comments[i], e);
         }
     });
 

test/specs/documentation/virtual.js

@@ -30,4 +30,24 @@ describe('virtual symbols', function() {
             expect(say.undocumented).not.toBeDefined();
         });
     });
+
+    describe('overloaded virtual symbols', function() {
+        var docSet = jasmine.getDocSetFromFile('test/fixtures/virtual3.js');
+        var constructors = docSet.getByLongname('module:connection');
+
+        it('should create multiple doclets for overloaded virtual symbols', function() {
+            expect(constructors).toBeDefined();
+            expect(constructors.length).toBe(2);
+        });
+
+        it('should use the correct signature for each virtual symbol', function() {
+            expect(constructors[0]).toBeDefined();
+            expect(constructors[0].params).toBeDefined();
+            expect(Array.isArray(constructors[0].params)).toBe(true);
+            expect(constructors[0].params[0].name).toBe('name');
+
+            expect(constructors[1]).toBeDefined();
+            expect(constructors[1].params).not.toBeDefined();
+        });
+    });
 });