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中未分配的类成员提供注释（特别是JSDoc）？是否有一个技巧可以使评论保持不变（即使转换后的代码中没有private _a;）？

Answer 1

是否有诀窍可以使评论留在原地？

你几乎肯定不想要这个。例如，以下代码不产生输出：

/** an interface */
interface Q { }

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

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

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

Answer 2

解决方法：

class A { /** * @private * @var _a */ private _b = undefined; /** * @public * @var a */ public a = true; }

[Playground]

<强>问题：

如何为TypeScript中未分配的类成员提供注释（特别是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 3

是否有诀窍可以使评论留在原地？

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

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定义为undefined，如下所示：

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在构造函数中表现完全相同的delete _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; }());

TypeScript删除注释并破坏JSDoc文档

4 个答案: