diff --git a/lib/jsdoc/src/handlers.js b/lib/jsdoc/src/handlers.js index ac2f4772..f25368e6 100644 --- a/lib/jsdoc/src/handlers.js +++ b/lib/jsdoc/src/handlers.js @@ -86,8 +86,20 @@ exports.attachTo = function(parser) { var memberofName = null, 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 + // A JSDoc comment can define a symbol name by including: + // + // + A `@name` tag + // + Another tag that accepts a name, such as `@function` + // + // When the JSDoc comment defines a symbol name, we treat it as a "virtual comment" for a + // symbol that isn't actually present in the code. And if a virtual comment is attached to + // a symbol, it's quite possible that the comment and symbol have nothing to do with one + // another. + // + // As a result, if we create a doclet for a `symbolFound` event, and we've already added a + // name attribute by parsing the JSDoc comment, we need to create a new doclet that ignores + // the attached JSDoc comment and only looks at the code. + if (newDoclet.name) { // try again, without the comment e.comment = '@undocumented'; newDoclet = getNewDoclet(e.comment, e);