Generator produces confusing output for export default class

[cincodenada]

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
      • .instanceMethod()
    • static
      • .staticMethod()

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 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.

[cincodenada]

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

ExampleClass

Classes

ExampleClass

ExampleClass

• ExampleClass
  • instance
    • .instanceMethod()
  • static
    • .staticMethod()

exampleClass.instanceMethod()

Does some instance stuff

Kind: instance method of ExampleClass

ExampleClass.staticMethod()

Does some static stuff

Kind: static method of ExampleClass

ExampleClass

Kind: global class

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.

[cincodenada]

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.

[dmnsgn]

It's also confusing when exporting both default export and named exports.