使用DocDash+JSDoc时@typedef未显示在目录的问题求助

一、修正代码注释与常量的关联 #

当前代码中@typedef和导出的常量是分开定义的，JSDoc无法将二者正确关联，导致Typedef的元数据不完整。修改注释，将Typedef与常量绑定：

/**
 * ActivityOptions 配置项类型定义
 * @typedef {object} module:CardSession.ActivityOptions
 * @property {boolean} quiz 开启测验模式
 * @property {boolean} canSkip 允许跳过内容
 * @property {boolean} repeat 允许重复操作
 * @property {number} timeLimit 时间限制（百分比）
 * @property {number} questionLimit 题目数量限制
 * @property {PassingProps} passingProps 通关所需属性
 * @property {string[]} prereq 前置条件ID列表
 * @property {string[]} completion 完成条件ID列表
 * @property {EnumActivityRules} rules 活动规则枚举
 */

/**
 * ActivityOptions的JSON Schema校验规则
 * @type {module:CardSession.ActivityOptions}
 * @memberof module:CardSession
 */
export const ActivityOptions = {
    type: 'object',
    properties: {
        quiz: {type: 'boolean'},
        canSkip: {type: 'boolean'},
        repeat: {type: 'boolean'},
        timeLimit: {type:'number'},
        questionLimit: {type: 'number'},
        passingProps: PassingProps,
        prereq: {
            type: 'array',
            items: {type: 'string'} // 修正JSON Schema规范：用items替代members
        },
        completion: {
            type: 'array',
            items: {type: 'string'}
        },
        rules: EnumActivityRules
    },
    required: ['quiz','canSkip','repeat','passingProps','prereq','completion','rules'],
    additionalProperties: false
};

二、调整DocDash配置显示Typedefs目录 #

原配置的sectionOrder中没有包含Typedefs，导致目录里不会单独列出该板块。更新jsdoc.json的DocDash配置：

{
    "docdash": {
        "static": true,
        "sort": true,
        "sectionOrder": [
            "Classes",
            "Tutorials",
            "Modules",
            "Typedefs", // 新增该行，将Typedefs加入顶部目录
            "Externals",
            "Events",
            "Namespaces",
            "Mixins",
            "Interfaces"
        ],
        "disqus": "musicards.io",
        "search": true,
        "commonNav": false,
        "collapse": true,
        "wrap": false,
        "typedefs": true,
        "navLevel": 1,
        "private": true,
        "removeQuotes": "none",
        "scripts": [],
        "ShortenTypes": false,
        "scopeInOutputPath": true,
        "nameInOutputPath": true,
        "versionInOutputPath": true
  }
}

三、确保Typedef可被搜索 #

按照以下步骤排查搜索问题：

• 确保@typedef添加了明确的描述文本，帮助JSDoc生成可搜索的元数据
• 检查@memberof的模块路径是否正确（如module:CardSession），避免拼写错误
• 重新生成文档前删除旧的输出目录，清除缓存后再运行JSDoc命令

四、调整模块内Typedef的排序 #

若Typedef在模块详情页中仍排在函数之后，可：

• 确保sort: true已开启，JSDoc会按名称首字母自动排序
• 若需要强制Typedef排在最前，可修改DocDash模板的排序逻辑（需自定义模板文件）

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