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

【问题标题】：Typescript: Are there any conventions to document code with comments?打字稿：是否有任何约定来记录带有注释的代码？
【发布时间】：2017-08-14 08:48:13
【问题描述】：

我习惯于以特定方式记录 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 是否有类似的评论和文档约定？甚至是使用这些约定从代码 cmets（如 JavaDoc）生成 html 文档页面的工具？

【问题讨论】：

标签： c# typescript documentation comments conventions

【解决方案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 工具可以在此约定中解析 cmets 并以 HTML 格式生成文档页面。

【讨论】：

【解决方案2】：

是的。

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

【讨论】：

谢谢，我刚刚意识到，Visual Studio 也支持这种格式的 cmets。只需在方法之前的行中输入/**，它就会插入带有自动生成的@param 元素的注释。
JSDoc 不应该是首选，因为它提供了与 Typescript 无关的类型注释，因为它是一种强类型语言。