JSDoc无法为HTML文件生成结构说明文档，因其解析器仅支持JavaScript语法，对HTML标签、属性等完全无感；强行解析会报错或静默失败，需改用cheerio等工具静态分析DOM树并导出结构数据。
JSDoc 不能直接为 HTML 文件生成结构说明文档——它只解析 JavaScript 代码中的注释，对 .html 文件里的标签、属性或 DOM 结构完全无感。想靠 jsdoc index.html 输出页面结构文档，会得到空结果或报错。
为什么 jsdoc 命令对 HTML 文件无效
JSDoc 的解析器是 JS 语法驱动的：它读取文件后尝试用 Acorn 或类似引擎解析为 AST，而 HTML 不是合法的 JavaScript 语法。即使 HTML 中嵌了 <script> 块，JSDoc 也只处理其中的 JS 部分，忽略所有标签、class、data-* 属性、slot 分布等结构信息。
- 运行
jsdoc index.html通常静默失败，或报Unable to parse file错误 - 配置
source.includePattern强制包含.html后缀，也不会改变解析行为 - 插件如
jsdoc-html-plugin实际仍是包装 HTML 模板渲染 JS 文档，不是反向提取 HTML 结构
替代方案：用 cheerio + 自定义脚本提取 HTML 结构
若目标是“自动生成 HTML 页面的结构说明”（比如组件模板文档、区块层级图、data- 属性清单），需换工具链。推荐用 Node.js + cheerio 做静态分析：
- 安装：
npm install cheerio - 读取 HTML 文件，遍历节点，收集：
tagName、id、class、data-*属性、aria-*属性、子元素数量、是否含slot等 - 输出 JSON 或 Markdown 表格，再喂给 JSDoc 的
@example或独立文档页 - 示例片段（提取所有带
data-role的元素）：const $ = cheerio.load(html);<br>$('[data-role]').each((i, el) => {<br> console.log($(el).prop('tagName'), $(el).attr('data-role'));<br>});
如果坚持用 JSDoc，只能间接支持 HTML 结构说明
适用场景：你有一套基于 HTML 模板的 JS 组件（如 Web Component、Vue SFC 的 <template>），想把模板结构写进组件文档里。这时可：
立即学习“前端免费学习笔记（深入）”；
- 在 JS 文件中用
@example手动粘贴结构化 HTML 片段：/**<br> * 按钮组件<br> * @example<br> * <my-button variant="primary" size="large">点击我</my-button><br> */
- 用
@typedef定义 HTML 片段类型，配合@type标注函数返回值为该结构：/** @typedef {string} HTMLButtonFragment */<br>/** @type {HTMLButtonFragment} */<br>export const template = `<button class="btn">${text}</button>`; - 避免把整个 HTML 文件丢给 JSDoc；它不认
<div class="container">这种东西，只认function render() { ... }
真正自动化 HTML 结构文档的关键，不在 JSDoc 的注释规则，而在能否把 DOM 树变成可枚举、可分类、可导出的数据对象——这一步必须绕过 JSDoc，自己写解析逻辑。
