New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Generator produces confusing output for export default class
#270
Comments
I did some more testing of the
ModulesClassesExampleClass
exampleClass.instanceMethod()Does some instance stuff Kind: instance method of ExampleClass.staticMethod()Does some static stuff Kind: static method of ExampleClassnew module.exports()This does stuff I initially also missed that a key part of the suggestion in the |
export default class
I've read through some of the other issues and see this is something that's come up a few times, and after yet further testing am seeing different behavior when running on an individual file vs a directory - running against the individual file above actually seems to produce mostly correct output, besides the constructor documentation. I still think it's possible to make improvements here, but I'll have to come back to this with fresh eyes, I think. |
It's also confusing when exporting both default export and named exports. |
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.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 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@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.The text was updated successfully, but these errors were encountered: