HTML5中注释不能用作API注释，因其被浏览器忽略、JS无法读取、文档工具不识别；有效API注释应写在JS函数上方（JSDoc）、TS类型声明旁或后端路由文件中，或通过嵌入结构化元数据。
HTML5 本身没有“API 注释语法”—— 只是普通注释，浏览器完全忽略，也不会被 JS 引擎或文档生成工具（如 JSDoc、TypeDoc）识别为接口说明。
HTML 中的
很多人误以为在 HTML 文件里写 就能生成接口文档，实际不会生效。HTML 注释仅用于标记页面结构、临时禁用代码块或给团队成员留便签，不具备语义化描述能力。
- 所有
内容在 DOM 中不可见，JS 无法读取 - 主流文档工具（JSDoc、ESDoc、Swagger UI）不解析 HTML 注释
- 若把接口定义写在 HTML 里，会导致逻辑与视图耦合，违反关注点分离原则
真正有效的 API 接口注释该写在哪
接口契约必须和可执行代码绑定，才能保障一致性。正确位置只有三个：
-
JavaScript 函数上方：用 JSDoc 格式写在
function或export前，配合/** */ -
TypeScript 接口/类型声明旁：用
/** */描述interface或type的用途和字段含义 -
后端路由文件中：如 Express + Swagger-UI 使用
@openapi注释块，或 FastAPI 的 docstring + Pydantic model 注释
例如前端调用接口的函数注释：
立即学习“前端免费学习笔记（深入）”；
/**
* 获取用户详情
* @param {string} userId - 用户唯一标识，长度 12~32 位字母数字组合
* @returns {Promise<{name: string, email: string}>} 用户基本信息对象
* @throws {Error} 当 userId 格式错误或服务返回 404 时抛出
*/
export async function fetchUser(userId) {
// 实现略
}如果非要在 HTML 里体现接口信息，只推荐一种安全方式
用 嵌入结构化元数据，而不是注释。这种方式可被 JS 读取、校验，也能被构建工具提取。
- 不污染 HTML 主体结构
- 避免注释被压缩工具（如 html-minifier）意外删掉
- 支持 JSON Schema 验证字段必填性、类型、格式
示例：
真正的接口文档从来不是靠 HTML 注释撑起来的；它依赖代码即文档（Code as Documentation）的实践——注释必须紧贴实现、可验证、可提取。把 API 说明塞进 里，等于把钥匙焊死在门框上，门没开，人先迷路了。
