Typescript：是否有用注释记录代码的约定？

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

Answer 1

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 格式的文档页面。

Answer 2

是的，有。

最常用的注释约定（毫不奇怪）来自 jsdoc 形式的 javascript。例如，VSCode 支持它们开箱即用。 还有一些专门为打字稿文档生成而开发的工具，例如 typedoc