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

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

是的,有.

最常用的评论约定(毫不奇怪)来自jsdoc形式的javascript.例如,VSCode 开箱即用.还有一些专门为打字机doc生成开发的工具,如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 格式的文档页面。