打字稿：是否有任何约定来记录带有注释的代码？

Question

我习惯于以特定方式在我们的 C# 项目中记录代码以提高团队生产力，在 Visual Studio 中受益于 Intellisense 等等

代码类似于：

/// <summary>
/// Loads a user with a specific id.
/// </summary>
/// <param name="id">The id of the user to search for.</param>
/// <returns>A user with the given id.</returns>
public User GetUserById(string id) {
    ...
}

Typescript 是否有类似的注释和文档约定？或者甚至是使用这些约定从代码注释（如 JavaDoc）生成 html 文档页面的工具？

Answer 1

是的，有。

最常用的注释约定（毫不奇怪）来自 javascript，形式为 jsdoc. For example VSCode support them out of the box。还有一些专门为 typescript 文档生成开发的工具，例如 typedoc

Answer 2

TSDoc 是最新提议的 Typescript 源文件注释和文档约定。它的表示法如下 -

/**
 * 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`
 */
function getAverage(x: number, y: number): number {
  return (x + y) / 2.0;
}

TypeDoc 工具可以解析此约定中的注释并生成 HTML.

中的文档页面

打字稿：是否有任何约定来记录带有注释的代码？

Typescript: Are there any conventions to document code with comments?

c#

typescript

documentation

comments

conventions