17370845950

HTML中不能用注释写函数说明，必须用/* /格式的JSDoc注释紧贴函数声明，且仅在.js/.ts文件中生效；HTML内联script中的JSDoc无法被工具识别或生成文档。

HTML 里不能用注释写函数说明

HTML 是标记语言，不解析 JavaScript 函数， 注释只在 HTML 层面生效，对 JS 函数完全无效。你在 标签里用 ，浏览器不会报错，但这段注释既不会被 JS 引擎读取，也无法被文档生成工具（如 JSDoc）识别。

JSDoc 注释必须写在函数声明上方且用 /** */

给 JS 函数加可维护的说明，要用标准 JSDoc 语法：以 /** 开头、*/ 结尾，每行以 * 对齐，描述、参数、返回值等用特定标签标识。关键点：

• @param 后跟 {类型} 和参数名，类型必须用花括号包裹，例如 @param {string} name
• @returns 或 @return 后也要写 {类型}，如 @returns {number}
• 注释块必须紧贴函数声明（中间不能有空行），否则 JSDoc 工具会认为它不属于该函数
• 不要混用 // 或 /* */ —— 它们不被 JSDoc 解析器识别为结构化注释

/**
 * 计算两个数字的和
 * @param {number} a 第一个加数
 * @param {number} b 第二个加数
 * @returns {number} 求和结果
 */
function add(a, b) {
  return a + b;
}

VS Code 和 TypeScript 能直接读取 JSDoc 提示

只要注释格式正确，VS Code 在调用函数时会自动显示参数名、类型和描述；TypeScript 编译器也能据此做类型检查（尤其配合 @typedef 自定义类型时）。但前提是：

• 文件后缀是 .js 或 .ts，不是内联
• 没有拼错标签，比如写成 @paramter 或漏掉 {}
• 函数不是箭头函数匿名定义在对象字面量里（如 obj: { fn: () => {} }），这种场景 JSDoc 支持有限

HTML 中真要“注释函数”，只能靠开发者自觉写在 外部

如果必须把函数说明塞进 HTML 文件（比如教学示例或极简原型），唯一合理做法是：把 JSDoc 注释写在 标签外部、作为 HTML 注释说明，再在 内部重复写一次精简版 JSDoc —— 但这本质是人工同步，无自动化保障。

真正容易被忽略的是：很多人以为把 JSDoc 往 HTML 里一贴就“文档化”了，其实没绑定构建流程（比如 typedoc、jsdoc）的话，这些注释永远只是代码里的静态文本，不会生成网页文档，也不会参与类型校验。