<p>HTML中不能用<!-- -->注释写函数说明，必须用/* /格式的JSDoc注释紧贴函数声明，且仅在.js/.ts文件中生效；HTML内联script中的JSDoc无法被工具识别或生成文档。</p>
HTML 里不能用注释写函数说明
HTML 是标记语言，不解析 JavaScript 函数，<!-- --> 注释只在 HTML 层面生效，对 JS 函数完全无效。你在 <script> 标签里用 <!-- function xxx() { ... } -->，浏览器不会报错，但这段注释既不会被 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，不是内联<script> - 没有拼错标签，比如写成
@paramter或漏掉{} - 函数不是箭头函数匿名定义在对象字面量里（如
obj: { fn: () => {} }），这种场景 JSDoc 支持有限
HTML 中真要“注释函数”，只能靠开发者自觉写在 <script> 外部
如果必须把函数说明塞进 HTML 文件（比如教学示例或极简原型），唯一合理做法是：把 JSDoc 注释写在 <script> 标签外部、作为 HTML 注释说明，再在 <script> 内部重复写一次精简版 JSDoc —— 但这本质是人工同步，无自动化保障。
立即学习“前端免费学习笔记（深入）”；
<!--
函数说明：
add() 接收两个 number，返回它们的和。
使用示例：add(2, 3) → 5
-->
<script>
/**
* @param {number} a
* @param {number} b
* @returns {number}
*/
function add(a, b) {
return a + b;
}
</script>真正容易被忽略的是：很多人以为把 JSDoc 往 HTML 里一贴就“文档化”了，其实没绑定构建流程（比如 typedoc、jsdoc）的话，这些注释永远只是代码里的静态文本，不会生成网页文档，也不会参与类型校验。
