JavaScript 块注释 - TypeScript

块注释是程序员编写代码时用来注释代码的一个非常重要的工具。在 JavaScript 中加入注释有助于更好地组织和理解代码，避免代码混乱和出错。在 TypeScript 中，块注释的使用也是一样的。

块注释的语法

在 JavaScript 和 TypeScript 中，块注释使用 /** ... */ 标记，格式如下：

/**
 * 这里写注释的内容
 * 
 * 可以换行，可以写多行
 */

注释内容可以使用 Markdown 格式，便于阅读和呈现。常用的 Markdown 标记如下：

• #: 一级标题
• ##: 二级标题
• ###: 三级标题
• ####: 四级标题
• -: 无序列表
• 1.: 有序列表
• >: 引用
• **: 粗体
• _: 斜体
• ---: 分割线

块注释的使用

在 JavaScript 中，块注释可以用来说明函数、类、接口、变量等的作用和参数。示例代码如下：

/**
 * 计算两个数的和
 * 
 * @param {number} x 第一个数
 * @param {number} y 第二个数
 * @returns {number} 返回两个数的和
 */
function add(x: number, y: number): number {
  return x + y;
}

在 TypeScript 中，块注释还可以用来定义函数类型，示例代码如下：

/**
 * 计算两个数的和
 * 
 * @param {number} x 第一个数
 * @param {number} y 第二个数
 * @returns {number} 返回两个数的和
 */
type AddFunction = (x: number, y: number) => number;

const add: AddFunction = (x, y) => x + y;

此处定义了一个 AddFunction 函数类型，参数为两个数字，返回值为数字。

块注释的工具

块注释虽然重要，但手动编写注释也是件十分繁琐、耗时的事情。幸好有一些编辑器可以方便我们编写块注释，比如 VS Code 的 Better Comments 插件。

Better Comments 可以让你在注释中使用不同的颜色，以便更好地区分注释的作用。比如，你可以使用 // TODO: 来标记需要做的工作，使用 // BUG: 来标记需要修复的问题，通过不同的颜色来区分。示例代码如下：

// TODO: 添加错误处理
function fetchData(url: string): Promise<any> {
  return fetch(url).then(res => res.json());
}

// BUG: 无法正确显示页面
function renderPage(): void {
  // ...
}

总结

块注释是程序员编写代码时用来注释代码的一个工具，可以使代码更易于理解和组织。在 JavaScript 和 TypeScript 中，块注释使用 /** ... */ 标记，要注意使用 Markdown 格式使注释更易于阅读和呈现。手动编写注释比较繁琐，可以使用编辑器插件来提高效率。