JSDoc生成文档层级异常：应继续用Object还是改用Class？

我来帮你拆解一下这个问题～你遇到的文档导航中子对象独立在外的情况，大概率是JSDoc注释没有明确标注嵌套关系导致的，不一定非要立刻改成Class——当然改用Class也是一种可行方案，下面分别给你说明两种思路：

方案1：调整JSDoc注释，保留对象字面量结构 #

JSDoc默认不会自动识别普通对象字面量的嵌套层级，你需要通过特定注释标签明确子对象属于父对象的一部分。常用的标签有@namespace、@memberof或者@typedef，这里给你两种实用的写法：

写法A：用@namespace + @memberof标记层级 #

这种方式适合直接给现有对象结构加注释，不需要额外定义类型：

/**
 * 全局页面对象
 * @namespace Page
 */
const Page = {
  /**
   * 页面头部组件
   * @memberof Page
   * @namespace Page.header
   */
  header: {
    /**
     * 获取头部标题文本
     * @returns {string} 标题内容
     */
    getTitle() {
      return document.querySelector('.header-title').textContent;
    },
    /**
     * 是否显示搜索框
     * @type {boolean}
     */
    hasSearch: true
  },
  // 其他子对象（如sidebar、footer）同理注释
};

通过@memberof Page明确header是Page的子成员，再用@namespace Page.header标记它自身也是一个命名空间，生成的文档就会把header嵌套在Page的导航节点下。

写法B：用@typedef定义结构化类型 #

如果你的对象结构比较复杂，用类型定义的方式会更清晰，也方便复用：

/**
 * 页面头部组件的类型定义
 * @typedef {Object} PageHeader
 * @property {function(): string} getTitle - 获取头部标题
 * @property {boolean} hasSearch - 是否显示搜索框
 */

/**
 * 全局页面对象的类型定义
 * @typedef {Object} PageObject
 * @property {PageHeader} header - 页面头部组件
 * @property {PageSidebar} sidebar - 页面侧边栏组件（可类似定义其他子对象）
 */

/**
 * 全局页面实例
 * @type {PageObject}
 * @global
 */
const Page = {
  header: {
    getTitle() {
      return document.querySelector('.header-title').textContent;
    },
    hasSearch: true
  },
  // 其他子对象实现...
};

这种方式通过类型关联，让JSDoc明确知道header是PageObject的属性，生成的文档会自动建立嵌套导航。

方案2：改用Class，兼顾结构与易读性 #

如果你愿意调整代码结构，Class的方式会让JSDoc的识别更自然，同时也能保持“随时访问所有方法属性”的优点。可以用静态属性来组织嵌套结构：

/**
 * 页面头部组件类
 */
class PageHeader {
  /**
   * 获取头部标题
   * @returns {string} 标题文本
   */
  getTitle() {
    return document.querySelector('.header-title').textContent;
  }

  /**
   * 是否显示搜索框
   * @type {boolean}
   */
  hasSearch = true;
}

/**
 * 全局页面对象类
 */
class Page {
  /**
   * 页面头部组件实例
   * @type {PageHeader}
   */
  static header = new PageHeader();

  // 其他子对象（如sidebar、footer）同理定义静态属性
}

这样生成的文档中，Page的静态属性header会直接关联到PageHeader类的文档，导航层级清晰，你依然可以通过Page.header.getTitle()这种直观的方式调用方法。

总结 #

• 如果想继续保留对象字面量的写法，只需要修正JSDoc注释，明确嵌套关系即可解决导航问题；
• 如果追求更规范的面向对象结构，改用Class也是不错的选择，且不会牺牲代码的易读性和便捷访问性。

内容的提问来源于stack exchange，提问作者user11771570