Description
I realize this has been brought up before, and there are workarounds that exist. But to sum up: if we're parsing the following file:
/**
* @module ExampleClass
*/
export default class ExampleClass {
/**
* This does stuff
*/
constructor () { }
/**
* Does some static stuff
*/
static staticMethod () { }
/**
* Does some instance stuff
*/
instanceMethod () { }
}
Because internally this gets rewritten to module.exports, the class and its constructor are exported as module.exports. This exposing of internal details of ES6 seems unhelpful, as it results in the following documentation:
ExampleClass
- ExampleClass
- module.exports ⏏
- new module.exports()
- instance
- static
- module.exports ⏏
module.exports ⏏
new module.exports()
This does stuff
module.exports.instanceMethod()
Does some instance stuff
Kind: instance method of module.exports
module.exports.staticMethod()
Does some static stuff
Kind: static method of module.exports
This is confusing and unfriendly to a user with reasonable JSDoc practices, I think. And while the single-default-export docs have an example of how to use @alias to circumvent this, in my view that solution is unintuitive and places more burden on the end-user than a documentation generator should.
Other similar solutions (such as the @module block) make sense outside the context of jsdoc-to-markdown, and I think they're reasonable requirements, it's reasonable to require a module be documented for a documentation generator to pick up on it. By contrast, this @alias tag/restructuring of the code does not make sense outside of the doc-generator context, and while this is a matter of taste, I think it makes the code slightly less comprehensible, if anything.
On its own it makes no sense to separate a single-export function or class from its module export statement, and then re-alias it back to the name it had before we did. Having to add tags and restructure my code specifically to get this tool to behave in a sensible way is frustrating and confusing as an end-user.
It would be much nicer if it could just handle this situation naturally, and use the module name in place of module.exports, since that's how folks will be generally using the module being documented.