文档注释标签

普通注释	文档注释
// 一句话说明``/* 多行说明 */	/** 文档说明，配合标签使用 */
给程序员看，不规范	可被工具识别、提取生成文档
不能自动补全	支持 IDE 自动提示（VSCode、WebStorm）
没有结构	有标准标签，结构化信息清晰

JSDoc 常用标签对照表（适用于 JS/TS）

标签	作用	示例
@description	描述函数、类、变量等的用途	@description 获取用户信息
@param（或 @params）	描述函数参数及类型（推荐用 @param）	@param {string} name 用户名
@returns / @return	描述函数返回值及类型	@returns {boolean} 是否成功
@interface	描述一个接口（interface）结构	@interface User
@typedef	定义一个类型别名	@typedef {Object} Config
@property	用于接口/对象的字段说明	@property {string} title 标题
@example	提供使用示例	@example \n getUser("Tom")
@deprecated	标记该函数/变量已废弃	@deprecated 请使用 getUserById
@throws	抛出的异常类型及说明	@throws {Error} 参数错误
@see	引用相关函数/文档	@see getUserById
@author	说明作者信息	@author Yumeng
@version	版本号	@version 1.0.0
@since	说明该功能从哪个版本开始提供	@since 2.0.0
@async	表示这是一个异步函数（async function）	@async

文档中的 $ 和 #

$ 和 # 是命令行里的提示符（prompt），表示你是在什么身份下输入命令， 不是命令本身，也不是命令的一部分。

$ 通常表示普通用户的命令行提示符，

# 通常表示管理员（root 用户）的命令行提示符。

文档里加 $ 或 # 是为了告诉读者“这是命令行里输入的命令”， 而不是命令的输出。

复制命令时，千万不要复制这些符号，只复制后面的命令内容。

$ ls -l
# apt update

代表“普通用户输入了 ls -l”

代表“管理员输入了 apt update”

# 在脚本里是注释符号，但在命令行提示符里是管理员身份的标志，两个概念不冲突。