TypeScript 删除注释并破坏 JSDoc 文档

Question

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

目前转译为 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

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

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

/** an interface */
interface Q { }

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

当 TS 和 JS 之间存在直接对应关系时，编译器会保留文档，严格来说是因为这样做没有任何坏处(即使实用性很小)。但它不会也不应该保留与其应用的代码分离的文档。

查看文档的最佳位置是直接在 TypeScript 源代码中(在您的编辑器中，或通过源映射)。 TypeScript 文件是您的源，而不是发出的 JS:使用 a TypeScript doc generator .编译或转译的代码不是文档的有用位置，并且保留问题所询问的特定文档会产生误导。