TypeScript注释的语法有文档吗?

它现在是否支持c# ///系统?


当前回答

当前的

TypeScript团队和其他涉及TypeScript的团队创建了一个TSDoc规范。https://tsdoc.org/

来自文档的例子:

export class Statistics {
  /**
   * Returns the average of two numbers.
   *
   * @remarks
   * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
   *
   * @param x - The first input number
   * @param y - The second input number
   * @returns The arithmetic mean of `x` and `y`
   *
   * @beta
   */
  public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
  }
}

Past

TypeScript使用JSDoc。如。

/** This is a description of the foo function. */
function foo() {
}

学习jsdoc: https://jsdoc.app/

但是您不需要在JSDoc中使用类型注释扩展。

你可以(也应该)使用其他jsdoc块标签,比如@returns等。

举个例子。关注类型(而不是内容)。

JSDoc版本(注意文档中的类型):

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

TypeScript版本(注意类型的重新定位):

/**
 * Takes two numbers and returns their sum
 * @param a first input to sum
 * @param b second input to sum
 * @returns sum of a and b
 */
function sum(a: number, b: number): number {
    return a + b;
}

其他回答

你可以像在常规JavaScript中那样使用注释:

1介绍 […TypeScript语法是ECMAScript 2015 (ES2015)语法的超集。

2基本概念 […本文描述了TypeScript添加的语法[…]

来源:TypeScript语言规范


规范中只有两次提到了“注释”这个词:

1介绍 […TypeScript还为JavaScript程序员提供了一个可选类型注释系统。这些类型注释类似于Closure系统中的JSDoc注释,但在TypeScript中,它们直接集成到语言语法中。这种集成使代码更具可读性,并降低了同步类型注释与其对应变量的维护成本。

11.1.1源文件依赖关系 […/// <引用路径="…"/>在源文件上添加依赖项 在path参数中指定。路径是相对于包含源文件的目录进行解析的。

当前的

TypeScript团队和其他涉及TypeScript的团队创建了一个TSDoc规范。https://tsdoc.org/

来自文档的例子:

export class Statistics {
  /**
   * Returns the average of two numbers.
   *
   * @remarks
   * This method is part of the {@link core-library#Statistics | Statistics subsystem}.
   *
   * @param x - The first input number
   * @param y - The second input number
   * @returns The arithmetic mean of `x` and `y`
   *
   * @beta
   */
  public static getAverage(x: number, y: number): number {
    return (x + y) / 2.0;
  }
}

Past

TypeScript使用JSDoc。如。

/** This is a description of the foo function. */
function foo() {
}

学习jsdoc: https://jsdoc.app/

但是您不需要在JSDoc中使用类型注释扩展。

你可以(也应该)使用其他jsdoc块标签,比如@returns等。

举个例子。关注类型(而不是内容)。

JSDoc版本(注意文档中的类型):

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

TypeScript版本(注意类型的重新定位):

/**
 * Takes two numbers and returns their sum
 * @param a first input to sum
 * @param b second input to sum
 * @returns sum of a and b
 */
function sum(a: number, b: number): number {
    return a + b;
}

TypeScript是JavaScript严格的语法超集

单行注释以//开头 多行注释以/*开始,以*/结束

你可以添加参数,返回信息等,以及使用:

/**
* This is the foo function
* @param bar This is the bar parameter
* @returns returns a string version of bar
*/
function foo(bar: number): string {
    return bar.toString()
}

这将导致像VS Code这样的编辑器显示如下:

2020年11月更新

现在有一个网站上线了,上面有所有可用的TSDoc语法(这太棒了):https://tsdoc.org/


作为参考,旧答案:

正确的语法现在是TSDoc使用的语法。它将允许Visual Studio Code或其他文档工具理解您的注释。

这里有一个关于语法的很好的概述,特别是这里。准确的规格应该“很快”写出来。

另一个值得查看的文件是这个文件,您将在其中看到有用的标准标记。

Note: you should not use JSDoc, as explained on TSDoc main page: Why can't JSDoc be the standard? Unfortunately, the JSDoc grammar is not rigorously specified but rather inferred from the behavior of a particular implementation. The majority of the standard JSDoc tags are preoccupied with providing type annotations for plain JavaScript, which is an irrelevant concern for a strongly-typed language such as TypeScript. TSDoc addresses these limitations while also tackling a more sophisticated set of goals.