Get the module tag to work correctly when it's combined with other JSDoc comments

[75lb]

i'm working on master with these files: https://gist.github.com/75lb/762bf8d94ba926492450

here's an exported function written in the style documented at usejsdoc.com:

/**
A simple maths function
@module
@example
var sum = require("sum");
*/
module.exports = sum;

/**
Sums two numbers together
@param {number} - first number 
@param {number} - second number
@returns {number} the result
@example
var result = sum(1, 1);
@alias module:sum-alias
*/
function sum(a, b){};

this file renders correctly in the generated documentation.

I re-wrote it to be more concise:

/**
A simple maths function
@module
@param {number} - first number 
@param {number} - second number
@returns {number} the result
@example
var sum = require("sum");
var result = sum(1, 1);
*/
module.exports = function sum(a, b){};

this did not render, is this the intended behaviour or a bug?

jsdoc2md/jsdoc-to-markdown#3

[hegemonic]

I'm guessing this was an unanticipated use case for the @module tag. JSDoc ought to support this, though.

Right now, the AST node for module.exports doesn't get attached to the module's doclet, which is awfully suspicious.

I wouldn't be surprised if #678 is caused by the same problem as this bug.

[75lb]

sounds like they are connected, if what you say is true.. obviously we can live without the concise version but it's a lot more user-friendly..

[hegemonic]

This change is going to be surprisingly difficult, if not impossible, to implement.

Here's why. A JSDoc comment can define a symbol name by including:

• A @name tag.
• Another tag that accepts a name, such as @function or @module.
• A tag that causes JSDoc to extract a name from the filename if there's no tag text. I believe that @file and @module are the only tags in this category.

If JSDoc is able to get a symbol name just by parsing the comment, it assumes that the comment is a "virtual comment" for a symbol that doesn't actually show up in the code. For example, if JSDoc parses the following source file, it correctly assumes that the JSDoc comment isn't related to the function declaration that follows it:

/** @module foo */

function bar(baz, qux) {}

To implement this change to the @module tag, I'd have to carve out some sort of exception to this general rule. For the moment, at least, I can't think of a backwards-compatible way to carve out that exception.

[hegemonic]

Updated the summary to match the actual issue more closely.