TypeScript 去除注释并破坏 JSDoc 文档

Question

目标是从 TypeScript 代码中获取 JSDoc 文档。 TypeDoc（TypeScript 文档解决方案）的文档质量是不可接受的，因为文档是针对 JS 用户的，不应该充斥着特定于 TypeScript 实现（接口等）的细节。

目前转译为 ES6 并从 JS 文件生成文档在很大程度上可以解决问题。没有赋值的属性除外。看起来，

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

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

正在被转译为

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

虽然我期待类似的东西

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

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

或

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

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

如何为 TypeScript 中未分配的类成员提供 cmets（尤其是 JSDoc）？有没有什么技巧可以让 cmets 保持原位（即使转译代码中没有 private _a;）？

Answer 1

解决方法：

class A {
    /**
     * @private
     * @var _a
     */
    private _b = undefined;

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

[Playground]

问题：

如何为 TypeScript 中未分配的类成员提供 cmets（尤其是 JSDoc）？

如果你看看负责构造函数生成的源代码：

• emitConstructor [line]
• |--- emitPropertyDeclarations(node, getInitializedProperties(node, /*isStatic*/ false)); [line]
• |------ getInitializedProperties [line]

您可以看到，无法自定义行为。

现有的文档生成工具

• TypeDoc

硬核方法：

TypeScript 提供编译器 API：https://github.com/Microsoft/TypeScript/wiki/Using-the-Compiler-API。可能，您可以遍历源代码并生成您喜欢的任何文档。

Answer 2

有没有什么技巧可以让 cmets 保持原位？

您几乎可以肯定实际上并不想要这个。例如，以下代码不产生任何输出：

/** an interface */
interface Q { }

如果编译器要保留文档，它们在许多（几乎所有）情况下都是多余的和误导性的。如果它出现在class C 上方，那么该文档似乎适用于该类（如果该类没有自己的文档，则更令人困惑）。如果我正在阅读您问题中的示例，我想知道this.a 实际上是第一个文档声称的@private，还是@public。其他程序员和您的工具没有正确的方法来解释这些杂散的文档。

当 TS 和 JS 之间存在直接对应关系时，编译器会保留文档，严格来说是因为这样做没有害处（即使实用程序很少）。但它不会也不应该保留与它们适用的代码分离的文档。

查看文档的最佳位置是直接在 TypeScript 源代码中（在您的编辑器中，或通过源映射）。您的源是 TypeScript 文件，而不是发出的 JS：使用 a TypeScript doc generator。编译或转译的代码对于文档来说不是一个有用的地方，并且保留问题所询问的特定文档会产生误导。

Answer 3

有什么技巧可以让 cmets 保持原位吗？

有点。您可以显式指定默认构造函数并将其他分离的 cmets 附加到它。变化：

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

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

到：

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

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

    constructor() {}

    private _a;

    private _b;
}

这将改变输出：

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

到：

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

这正是您想要的。这是可以找到的“最干净的技巧”。

Answer 4

将_a定义为未定义，如下所示：

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

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

编译成

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

编辑：

如果你希望 hasOwnProperty 在构造函数中的行为完全相同，请删除 _a：

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

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

    constructor() {
        delete this._a;
    }
}

编译成

var A = (function () {
    function A() {
        /**
         * @private
         * @var _a
         */
        this._a = undefined;
        /**
         * @public
         * @var a
         */
        this.a = true;
        delete this._a;
    }
    return A;
}());