use the correct comment when creating doclets for overloaded methods (#179)

lib/jsdoc/src/handlers.js

@@ -5,17 +5,17 @@
 
 var currentModule = null;
 
-function getNewDoclet(parser, comment, e) {
+function getNewDoclet(comment, e) {
     var jsdoc = {doclet: require('jsdoc/doclet')};
     var util = require('util');
     var err;
 
     try {
-        return new jsdoc.doclet.Doclet(e.comment, e);
+        return new jsdoc.doclet.Doclet(comment, e);
     }
     catch (error) {
-        err = new Error( util.format('cannot create a doclet in the file %s for the comment ' +
-            '"%s": %s', parser._currentSourceName, comment.replace(/[\r\n]/g, ''), error.message) );
+        err = new Error( util.format('cannot create a doclet for the comment "%s": %s',
+            comment.replace(/[\r\n]/g, ''), error.message) );
         require('jsdoc/util/error').handle(err);
         return new jsdoc.doclet.Doclet('', {});
     }
@@ -30,7 +30,7 @@ exports.attachTo = function(parser) {
 
     // handles JSDoc comments that include a @name tag -- the code is ignored in such a case
     parser.on('jsdocCommentFound', function(e) {
-        var newDoclet = getNewDoclet(parser, e.comment, e);
+        var newDoclet = getNewDoclet(e.comment, e);
 
         if (!newDoclet.name) {
             return false; // only interested in virtual comments (with a @name) here
@@ -57,13 +57,13 @@ exports.attachTo = function(parser) {
     // TODO: for clarity, decompose into smaller functions
     function newSymbolDoclet(docletSrc, e) {
         var memberofName = null,
-            newDoclet = getNewDoclet(parser, docletSrc, e);
+            newDoclet = getNewDoclet(docletSrc, e);
 
         // an undocumented symbol right after a virtual comment? rhino mistakenly connected the two
         if (newDoclet.name) { // there was a @name in comment
             // try again, without the comment
             e.comment = '@undocumented';
-            newDoclet = getNewDoclet(parser, e.comment, e);
+            newDoclet = getNewDoclet(e.comment, e);
         }
 
         if (newDoclet.alias) {

test/fixtures/also.js

@@ -1,6 +1,8 @@
 /** @class */
 function Asset() {
     this._name = '';
+    this._shape = '';
+    this._shhhhKeepThisSecret = '';
 }
 
 /**
@@ -17,4 +19,28 @@ function Asset() {
 Asset.prototype.name = function(newName) {
     if (newName) { this._name = newName; }
     else { return this._name; }
-}
+};
+
+/**
+ * Set the value of the shape property.
+ * @param {string} newShape
+ *//**
+ * Set the value of the shape property, plus some other property.
+ * @param {string} newShape
+ * @param {string} mysteryProperty
+ *//**
+ * Get the value of the shape property.
+ * @returns {string}
+ */
+Asset.prototype.shape = function(newShape, mysteryProperty) {
+    if (newShape && mysteryProperty) {
+        this._shape = newShape;
+        this._shhhhKeepThisSecret = mysteryProperty;
+    }
+    else if (newShape) {
+        this._shape = newShape;
+    }
+    else {
+        return this._shape;
+    }
+};

test/specs/documentation/also.js

@@ -1,10 +1,47 @@
+/*global describe: true, expect: true, it: true, jasmine: true */
 describe("multiple doclets per symbol", function() {
-    var docSet = jasmine.getDocSetFromFile('test/fixtures/also.js'),
-        name = docSet.getByLongname('Asset#name').filter(function($) {
-            return ! $.undocumented;
-        });
+    function undocumented($) {
+        return ! $.undocumented;
+    }
 
-    it('When a symbol has two doclets adjacent to each other both doclets apply to the symbol.', function() {
-        expect(name.length).toEqual(2);
+    function checkInequality(doclets, property) {
+        for (var l = doclets.length - 1; l > 0; l--) {
+            if (doclets[l][property] !== undefined && doclets[l - 1][property] !== undefined) {
+                expect(doclets[l][property]).not.toBe(doclets[l - 1][property]);
+            }
+        }
+    }
+
+    var docSet = jasmine.getDocSetFromFile('test/fixtures/also.js');
+    var name = docSet.getByLongname('Asset#name').filter(undocumented);
+    var shape = docSet.getByLongname('Asset#shape').filter(undocumented);
+
+    it('When a symbol has multiple adjacent JSDoc comments, both apply to the symbol.', function() {
+        expect(name.length).toBe(2);
+        expect(shape.length).toBe(3);
     });
-});
+
+    it('When a symbol has multiple adjacent JSDoc comments that are not identical, the doclets ' +
+        'have different comments.', function() {
+        checkInequality(name, 'comment');
+        checkInequality(shape, 'comment');
+    });
+
+    it('When a symbol has multiple adjacent JSDoc comments with different descriptions, ' +
+        'the doclets have different descriptions.', function() {
+        checkInequality(name, 'description');
+        checkInequality(shape, 'description');
+    });
+
+    it('When a symbol has multiple adjacent JSDoc comments with different numbers of ' +
+        '@param tags, the doclets have different parameter lists.', function() {
+        checkInequality(name, 'params.length');
+        checkInequality(shape, 'params.length');
+    });
+
+    it('When a symbol has multiple adjacent JSDoc comments with different numbers of ' +
+        '@returns tags, the doclets have different lists of return values.', function() {
+        checkInequality(name, 'returns.length');
+        checkInequality(shape, 'returns.length');
+    });
+});