Treat constructor method as proper constructor of an object

[lrowe]

With this minimal class:

/** */
class Foo {
  /** */
  constructor(bar) {
    this.bar = bar;
  }
}

Runningnode_modules/.bin/documentation serve doc.js produces the following output with 4.0.0-beta.18:

I would expect the constructor not to be displayed as an instance method and it's parameters included in the instantiation example.

[leonpegg]

This is exactly what i would of expected as well also if the constructor is not defined but class is extended should pull in the def from the parent class

[paulofaria]

yeah I'm getting the same issue. is there something we should be doing that we aren't?

[tmcw]

This is a known issue - so far documentation doesn't do any special treatment of constructor methods versus any other methods, and it should.

[leonpegg]

I have been working on my own theme that does additional processing of the json i will release the theme once completed, but I believe this additional processing should be done befre the theme stage

[tmcw]

Q:

Should you document a class like:

/**
  * I describe the class here, and use param tags here
  */
class Foo {
  /** */
  constructor(bar) {
    this.bar = bar;
  }
}

Or

/** */
class Foo {
  /**
    * I describe the class here, and use param tags here
    */
  constructor(bar) {
    this.bar = bar;
  }
}

I'm leaning toward the former, and trying an implementation now.

[tmcw]

Okay: I have a working branch that does the following:

• In parameter inference, when it encounters an ES6 class, it looks at the class's members and, if it finds a constructor, infers parameters from that constructor.
• Warns if a constructor is explicitly documented.

[arv]

I would have preferred to document the parameters on the constructor. Putting it on the class is just more out of bounds and more likely to get out of sync.

(But personally I do not document parameters and just let the inference do it's work.)

[tmcw]

Do other folks feel that way?

The reason why I opted for documenting them on the class was mostly that documenting them at the class level felt like the more natural way to express all the documentation in one place, rather than running into the weird case where you have a description at the class level and param details near the constructor and they're combined, and, following that thought, cases where people use params at the class level and also at the constructor level, or descriptions on both.

Handling that indecision / merging potentially conflicting details seemed like a source of uncertainty that could be avoided, but maybe it's outweighed by the directness of params sitting near their code position?

[kbirk]

Just to chime in here as one random opinion, I personally prefer putting the constructor parameter documentation above the constructor and the class property documentation above the class as @arv describes. I find this easier to read and maintain, especially when the arguments don't necessarily align with the properties, for example:

/**
 * A widget object which is used to blah blah blah.
 *
 * @property {HTMLElement} element - The containing element of the widget.
 */
class Widget {

    /**
     * Instantiate a widget object.
     *
     * @param {string} selector - The string selector for the element.
     */
    constructor(selector) {
        this.element = document.querySelector(selector);
    }
}

I guess this all comes down to personal preference though.

[jamesgpearce]

In my current use case, I don't want the constructor documented - nor its parameters - because the class is never instantiated by the user (with a kind of factory pattern). Seems like even if I /** @ignore * the constructor I get all its arguments appearing, rather confusingly, as parameters at the top of the class documentation. Is there any way to avoid this if the constructor is to be ignored?

[kbirk]

Any updates on this?

[tmcw]

At least for me, I've been taking a break from day-to-day work on this project in hope that other folks will join and contribute - so no updates from my side. But contributions / PRs would be incredibly welcome!