HTML 中的注释写法与常见误用
HTML 本身不支持带参数说明的注释语法， 只能写纯文本，不能解析成函数签名或类型提示。所谓“html5 注释写参数说明”，实际是开发者在 HTML 模板里手写文档式注释，用于辅助理解嵌入的 JS 逻辑、模板变量或组件接口。
容易踩的坑：把 当作可被工具识别的标准（像 JSDoc 那样），但浏览器和多数构建工具默认完全忽略这些注释，也不会校验参数名是否匹配真实代码。
- 注释内容不会出现在 dom 中，但会保留在源码里，影响加载体积（尤其大段说明）
- 若混用
内联脚本，别在 HTML 注释里写 JS 类型（如），这不属于任何标准，仅靠人工维护 - vue / Svelte 等框架的单文件组件中，
仍只是 HTML 注释，不是组件 Props 文档 —— 应该用上方的 JSDoc 或
JSDoc 风格注释必须写在 JS 代码中，而非 HTML
要真正实现“函数参数说明”，注释必须紧贴 JS 函数声明，使用标准 JSDoc 语法，并由支持 JSDoc 的工具（如 typescript、ESLint、Volar、ide）解析。HTML 文件里的 标签内可以写，但位置和格式有硬性要求。
正确示例（放在 内部，且紧邻函数）：
立即学习“前端免费学习笔记（深入）”；
/** * 格式化用户信息并插入到页面 * @param {String} name - 用户姓名，必填 * @param {number} age - 年龄，大于 0 * @param {boolean} [isActive=false] - 是否启用状态，可选 */ function renderUser(name, age, isActive = false) { document.getElementById('user').textContent = `${name} (${age})`; }-
@param后必须跟空格、类型（用花括号包裹）、参数名、短横线和说明 - 可选参数用方括号标记：
[isActive=false]，类型后不能加问号（那是 TypeScript 语法，JSDoc 不认） - 注释块必须用
/** */，不能用//或 - 若 HTML 中通过
引入外部 JS，则注释必须写在那个 .js 文件里，HTML 中写无效
HTML 模板中模拟参数说明的实用做法
当 HTML 作为模板（如 php、Django、Nunjucks 渲染上下文）时，开发者常在注释中“手写接口契约”。这不是标准，但团队约定后可提升可读性。关键是要保持简洁、一致、不与真实逻辑耦合。
推荐写法（以含变量的静态 HTML 片段为例）：
@@##@@" alt="<%= name %>"> <%= name %>
- 用
Props：明确区分这是接口描述，不是运行时注释 - 类型用简写（
string、number），枚举值用单引号包裹（'vip'），可选用optional或默认值标注 - 避免写复杂类型（如
{id: number, tags: string[]}），这类应移至配套 JS 或类型定义文件 - 不要在注释里写逻辑（如 “如果 badge 是 vip 则加金边”），样式/行为应由 css 类或 JS 控制，注释只管“传什么”
TypeScript + HTML 混合项目中的真实约束点
如果你用 TypeScript 编写逻辑、HTML 仅作结构，那么“参数说明”的权威来源只能是 TS 接口或类型定义，HTML 注释没有任何校验能力。强行在 HTML 里重复写参数，反而增加维护成本和不一致风险。
例如，一个组件接收的 props 应定义为：
Interface UserCardProps { name: string; avatarUrl?: string; badge?: 'vip' | 'new'; }然后在调用处（JSX 或模板字符串）由 IDE 提示补全，而不是靠 HTML 注释记忆。
- HTML 注释无法防止传错类型（比如传了
avatarUrl={123}），只有 TS 能做这件事 - 构建工具（如 vite + vue-tsc）会检查 TS 类型，但完全无视
- 如果团队坚持 HTML 内写文档，建议只写高阶说明（如“此区域由后端 json 渲染，字段见 /api/user/schema”），把细节交给接口文档或 TS 类型
真正起作用的参数说明，永远绑定在可执行、可校验、可跳转的代码位置上 —— 不是 HTML 注释，而是函数上方的 JSDoc，或是 .d.ts 文件里的 interface。HTML 里的文字，顶多算便签。
