cincodenada
commented
2 years ago I did some more testing of the @alias workaround and have updated my comment above, I initially said it suppresses the constructor, if you add an @alias but don't restructure, but it just doesn't apply the alias to it (even if I explicitly alias the constructor method instead of the class, which I understand are the same thing as far as JS is concerned), and thus it gets added to its own duplicate section:
/**
* @module ExampleClass
*/
export default class ExampleClass {
/**
* This does stuff
* @alias ExampleClass
*/
constructor () {
console.log('whee')
}
/**
* Does some static stuff
*/
static staticMethod () { }
/**
* Does some instance stuff
*/
instanceMethod () { }
}Modules
Classes
ExampleClass
- ExampleClass
- instance
- static
exampleClass.instanceMethod()
Does some instance stuff
Kind: instance method of ExampleClass
ExampleClass.staticMethod()
Does some static stuff
Kind: static method of ExampleClass
ExampleClass
new module.exports()
This does stuff
I initially also missed that a key part of the suggestion in the @alias workaround is to restructure your code to separate the export from the class delcaration, in addition to alias'ing it back to the module name. To me that just reinforces my opinion that asking users to restructure not only their JSDoc declarations, but the code itself, in order to get a documentation generation utility to parse it correctly, is a suboptimal solution. export default class is a common pattern, and I think the this project should handle it gracefully if we can.
dmnsgn
75lb
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:
Because internally this gets rewritten to
module.exports, the class and its constructor are exported asmodule.exports. This exposing of internal details of ES6 seems unhelpful, as it results in the following documentation:ExampleClass
module.exports ⏏
Kind: Exported class
new module.exports()
This does stuff
module.exports.instanceMethod()
Does some instance stuff
Kind: instance method of
module.exportsmodule.exports.staticMethod()
Does some static stuff
Kind: static method of
module.exportsThis 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
@moduleblock) make sense outside the context ofjsdoc-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@aliastag/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.