如何使用 JSDoc Typescript 声明隐藏“私有”方法？

Question

假设我有一个 JavaScript 类

/**
 * @element my-element
 */
export class MyElement extends HTMLElement {
  publicMethod() {}
  /** @private */
  privateMethod() {}
}

customElements.define('my-element', MyElement);

以及使用declaration 和allowJs 生成的声明文件：

export class MyElement extends HTMLElement {
  publicMethod(): void;
  /** @private */
  privateMethod(): void
}

我还在构建后脚本中将其连接到声明文件：

declare global { interface HTMLElementTagNameMap { 'my-element': MyElement; } }

在打字稿文件中使用此元素时，我可以在自动完成中访问privateMethod。

import 'my-element'
const me = document.createElement("my-element")
me.// autocompletes `privateMethod`

如何指示tsc 将使用@private JSDoc 标记注释的任何方法、字段或属性标记为私有？

Answer 1

根据 JSDoc 文档，使用 /** @private */ 是正确的语法，但这不是 TypeScript 处理它的方式。您需要利用 TypeScripts 语法来处理这个问题，它不能单独与 JSDoc 一起使用。

TypeScript 3.8 and up supports ES6 style private fields。您可以在方法的开头使用 # 符号来表示私有字段，如下所示：

class Animal {
  #name: string;
  constructor(theName: string) {
    this.#name = theName;
  }
}

// example

new Animal("Cat").#name;
Property '#name' is not accessible outside class 'Animal' because it has a private identifier.

或者，TypeScript also allows you to declare a field as private 使用private 标记，将提供所需的结果。这样做不会在自动完成期间显示privateMethod（至少对我来说不会）。

/**
 * @element my-element
 */
class MyElement extends HTMLElement {
  publicMethod() {}
  /** @private */
  private privateMethod() {}
}

let element = new MyElement()

element.privateMethod()
// Error: Property 'privateMethod' is private and only accessible within class 'MyElement'.

这是一个使用 VS Code 智能感知的示例。

Answer 2

确保您使用的是正确版本的打字稿。 Typescript 3.8 添加了support for this，使用Typescript 3.8 或heigher 应该支持@private jsdoc 修饰符。

您可以使用tsc -h 获取有关已安装的打字稿编译器版本的信息。

Answer 3

您需要为那些希望从文档中排除的方法和类使用 @ignore 注释。

@ignore 标记表示代码中的符号永远不应出现在文档中。

/**
 * @class
 * @ignore
 */
function Jacket() {
    /** The jacket's color. */
    this.color = null;
}

/**
 * @namespace
 * @ignore
 */
var Clothes = {
    /**
     * @class
     * @ignore
     */
    Jacket: function() {
        /** The jacket's color. */
        this.color = null;
    }
};

更多信息在这里：https://jsdoc.app/tags-ignore.html