TypeScript strips down comments and spoils JSDoc documentation

Question

The objective is to get JSDoc documentation from TypeScript code. The quality of documentation from TypeDoc (TypeScript documentation solution) isn't acceptable because the documentation is targeted at JS users and shouldn't be flooded with the details that are specific to TypeScript implementation (interfaces, etc).

Currently transpiling to ES6 and generating the documentation from JS files does the trick for the most part. Except for the properties that have no assigned values. As it appears,

class A {
    /**
     * @private
     * @var _a
     */
    private _a;

    /**
     * @public
     * @var a
     */
    public a = true;
}

is being transpiled to

class A {
    constructor() {
        /**
         * @public
         * @var a
         */
        this.a = true;
    }
}

While I would expect something like

class A {
    constructor() {
        /**
         * @private
         * @var _a
         */

        /**
         * @public
         * @var a
         */
        this.a = true;
    }
}

or

class A {
    /**
     * @private
     * @var _a
     */

    constructor() {
        /**
         * @public
         * @var a
         */
        this.a = true;
    }
}

How can comments (particularly JSDoc) be provided for unassigned class members in TypeScript? Is there a trick that could make the comments stay in place (even if private _a; is absent from transpiled code)?

Answer 1

Is there a trick that could make the comments stay in place?

You almost certainly don't actually want this. For example, the following code produces no output:

/** an interface */
interface Q { }

If the compiler were to preserve the docs, they would in many (nearly all) cases be superfluous and misleading. If that appeared above a class C, then the doc would seem to apply to the class (even more confusing if that class had no docs of its own). If I were reading the example in your question, I would wonder whether this.a was actually @private as the first doc claimed, or @public. There is no right way for other programmers and for your tools to interpret these stray docs.

The compiler preserves docs when there is a direct correspondence between the TS and JS, strictly because there is no harm in doing so (even though there is very little utility). But it does not, and should not, preserve docs that are detached from the code they apply to.

The best place to look at docs is directly in the TypeScript source (in your editor, or via sourcemaps). It's the TypeScript file that is your source, not the emitted JS: use a TypeScript doc generator. Compiled or transpiled code is not a useful place for docs, and carrying over the particular docs that the question is asking about would be misleading.

Answer 2

Is there a trick that could make the comments stay in place?

Somewhat. You can explicitly specify the default constructor and attach the otherwise detached comments to it. Change:

class MyClass {
    /**
     * @private
     * @var _a
     */
    private _a;

    /**
     * @private
     * @var _b
     */ 
    private _b;
}

to:

class MyClass {
    /**
     * @private
     * @var _a
     */

    /**
     * @private
     * @var _b
     */

    constructor() {}

    private _a;

    private _b;
}

This will change the output from:

var MyClass = (function () {
    function MyClass() {
    }
    return MyClass;
})();

to:

var MyClass = (function () {
    /**
     * @private
     * @var _a
     */
    /**
     * @private
     * @var _b
     */
    function MyClass() {
    }
    return MyClass;
})();

Which is exactly what you want. This is the "cleanest trick" to be found.