API Docs: classes in modules

[anehx]

Currently, if we have a class in a module e.g my-addon/lib/some-class.js which looks like this:

/**
 * Some class which does some stuff..
 *
 * @class SomeClass
 */
export default class SomeClass {
  /**
   * Some method which magically always returns 42
   *
   * @method someMethod
   * @return {Number} Always 42
   */
  someMethod() {
    return 42
  }
}

As a user I'd expect to see this class documented the same as if it was located in my-addon/service/some-service. I'd expect to see the documented properties, accessors, methods etc.

What do you think about this? Is there a reason that this is implemented like this?

[pzuraq]

Currently, classes should be listed on the module page, and clicking on the class should take you to a separate class page which is similar to service/component documentation.

The current implementation covers the case where a module can export multiple classes, a class and some helper functions, etc. unfortunately this is something we do have to consider, because it’s perfectly valid in JS to do this.

@samselikoff and I were discussing this and we definitely think there should be shortcuts when a module has only one export, at least. It’s a tough design problem, and we’re open to suggestions!

[samselikoff]

I have some code for this, just need to get back around to it. I think we'll be able to support these "special cases".