JSDoc是否支持在独立文件定义术语并关联引用,且适配VS Code跳转
实现方案
该需求完全可以实现,以下是两种可落地的适配方案,均支持VS Code的悬停查看与跳转能力:
方案1:使用JSDoc @typedef 定义术语(最优适配VS Code)
该方案不需要调整原有代码中{@link grokelates}的写法,仅需新增一个全局术语定义文件即可:
- 在项目根目录新建专门存放术语定义的文件,例如命名为
glossary.js,无需编写业务逻辑,仅存放JSDoc定义:
/** * 自定义术语:指对输入参数执行特定的序列化、特征提取与上下文关联的处理流程,是本项目grokelation体系的核心操作逻辑。 * @typedef {any} grokelates * @description 所有涉及grokelation相关逻辑的处理都需遵循项目内部grokelation规范的流程要求 */
其中@typedef后的any仅为占位符,不会影响实际代码的类型检测,仅用于让JSDoc识别该自定义术语标识。
2. 配置完成后,VS Code会自动识别全项目内的{@link grokelates}引用,悬停可查看术语说明,Ctrl/Command + 点击即可直接跳转到glossary.js中的定义位置。
方案2:使用本地Markdown术语表链接
如果希望术语表可直接供非开发角色查看,可将术语存放在纯Markdown文件中,调整JSDoc的链接写法即可:
- 新建术语表Markdown文件,例如
docs/GLOSSARY.md,在其中定义对应术语并设置锚点:
## grokelates 指对输入参数执行特定的序列化、特征提取与上下文关联的处理流程,是本项目grokelation体系的核心操作逻辑。 所有涉及grokelation相关逻辑的处理都需遵循项目内部grokelation规范的流程要求。
- 调整原有JSDoc的link写法,指向本地Markdown文件的对应锚点:
/** * Takes a foo and {@link ../../docs/GLOSSARY.md#grokelates|grokelates} it. */ function doSomething(foo) { }
点击链接时VS Code会直接打开对应的Markdown文件,并滚动到术语定义的位置。
注意事项
- 术语表文件需放在VS Code的当前工作区范围内,才能正常触发跳转、悬停识别
- 团队内统一使用同一种方案即可,避免混合使用导致维护混乱
内容的提问来源于stack exchange,提问作者Instance Hunter
相关产品推荐
相关产品推荐

