html5中注释不能用作api注释，因其被浏览器忽略、js无法读取、文档工具不识别；有效api注释应写在js函数上方（jsdoc）、ts类型声明旁或后端路由文件中，或通过嵌入结构化元数据。
HTML5 本身没有“API 注释语法”——<!-- --> 只是普通注释，浏览器完全忽略，也不会被 JS 引擎或文档生成工具（如 JSDoc、TypeDoc）识别为接口说明。
HTML 中的 <!-- --> 不能当 API 注释用
很多人误以为在 HTML 文件里写 <!-- @param userId {string} 用户唯一标识 --> 就能生成接口文档，实际不会生效。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 里体现接口信息，只推荐一种安全方式
用 <script type="application/json"></script> 嵌入结构化元数据，而不是注释。这种方式可被 JS 读取、校验，也能被构建工具提取。
- 不污染 HTML 主体结构
- 避免注释被压缩工具（如 html-minifier）意外删掉
- 支持 JSON Schema 验证字段必填性、类型、格式
示例：
<script type="application/json" id="api-spec">
{
"endpoint": "/api/v1/users/{id}",
"method": "GET",
"params": {
"id": { "type": "string", "pattern": "^[a-zA-Z0-9]{12,32}$" }
},
"response": {
"200": { "name": "string", "email": "string" }
}
}
</script>真正的接口文档从来不是靠 HTML 注释撑起来的；它依赖代码即文档（Code as Documentation）的实践——注释必须紧贴实现、可验证、可提取。把 API 说明塞进 <!-- --> 里，等于把钥匙焊死在门框上，门没开，人先迷路了。
