Not recognising documentation for class properties in JS files

[danprince]

It seems like Typedoc doesn't support the @type tag that TypeScript recommends using to add types to class properties in JavaScript projects.

Example from the official handbook.

class C {
    constructor() {
        /** @type {number | undefined} */
        this.prop = undefined;
        /** @type {number | undefined} */
        this.count;
    }
}

I have a project which documents properties this way extensively, but none of them end up in the generated documentation (regardless of visibility modifiers etc).

  /**
   * Font represents a bitmap font that will be used to render for a terminal.
   *
   * @param {object} settings
   * @param {string} settings.url The url for the font's image
   * @param {number} [settings.columns] The number of columns in the font's image
   * @param {number} [settings.rows] The number of rows in the font's image
   * @param {boolean} [settings.graphical] Specify whether the font is already colored
   * @param {number} [settings.transparentColor] Transparency key for the font image in numeric RGBA format
   */
  constructor({
    url,
    columns = 16,
    rows = 16,
    graphical = false,
    transparentColor = 0x00000000,
  }) {
    /**
     * @type {HTMLImageElement}
     * @readonly
     * @private
     */
    this.image = new Image();
    this.image.src = url;

    /**
     * The width (in characters) of this font.
     *
     * @readonly
     */
    this.columns = columns;

    /**
     * The height (in characters) of this font.
     *
     * @readonly
     */
    this.rows = rows;

The constructor, accessors and all the methods are present in the generated docs, but no properties.

[Gerrit0]

The cause of this is that we currently find members by looking at the AST nodes. We should instead be using the type checker.

[danprince]

Is using the type checker something that might happen in the short term future?

Might be naive (because I haven't been through the codebase) but what about just parsing property assignments for this inside the constructor, once you have the AST?

[Gerrit0]

Unfortunately probably not very short term :/

Right now the whole converter structure is based on iterating over the nodes of a file. I'm guessing the type checker API wasn't nearly as complete when it was written so we couldn't just use it. Reworking the converters to use the type checker is something that needs to happen (maybe even for library mode to work, I've been running into a bunch of issues with the node based conversion)

It should be possible to look inside the constructor as you suggest should fix this, PR welcome if you'd like to give it a try. The code should probably be around here - https://github.com/TypeStrong/typedoc/blob/master/src/lib/converter/nodes/constructor.ts#L26

[Gerrit0]

In 0.20, we get the properties in a reasonable manner, by asking the type checker... but are still relying on nodes in order to find the comment, so they remain undocumented. Unfortunately, resolving this is... tricky. We can't use symbol.getDocumentationComment() to retrieve the comment (at least in all cases..) because that merges comments together on declaration-merged symbols, which is entirely undesirable. Still going to leave this open... but I'm not sure about a resolution.

[fenomas]

Hi, just wanted to ping how useful it would be if this could be addressed. I've been delving into using typedoc for JS, and almost everything works beautifully. But this one issue is the blocker; the only workaround seems to be declaring typedefs for every class that duplicate every class property. (or use JSdoc, which unfortunately has a host of other problems..)

[Gerrit0]

Well, turns out sometimes all that's necessary is a break of a few months... Literally a one line change to make this work.

[fenomas]

Brilliant, thanks!

Incidentally I found an okay workaround for anyone waiting for the next version:

/** class comment */
class Foo {

    /** 
     * Property comment
     * @prop bar
     */

    /** constructor comment */
    constructor() {
        this.bar = 1
    }
}

The standalone property comments need to be inside the class but outside the constructor, and they need a @prop propname decorator to match up to the property. Then things work as expected, including inferring the property's type from its declaration inside the class.