VSCode中JS项目JSDoc注释未在IntelliSense显示的解决咨询

我有一个JavaScript代码库，正在添加TypeScript类型定义，目的是让VSCode的IntelliSense能在JS文件中提供类型与描述提示。目前类型显示正常，但JSDoc注释始终无法显示。我尝试了三种定义RunFunction接口的方式：

尝试1 #

interface RunFunction {
  /**
   * @param argv arguments passed from command line
   * @param config global config
   * @returns void
   */
  (
    argv: typeof import('./index.js').argv,
    config: typeof import('./index.js').config,
  ): void;
} 

尝试2 #

/**
 * @param argv arguments passed from command line
 * @param config global config
 * @returns void
*/
interface RunFunction {
  (
    argv: typeof import('./index.js').argv,
    config: typeof import('./index.js').config,
  ): void;
} 

尝试3 #

interface RunFunction {
  (
    /** arguments passed from command line */
    argv: typeof import('./index.js').argv,
    /** global config */
    config: typeof import('./index.js').config,
  ): void;
} 

我还尝试了上述方式的不同组合，但在JS文件中使用时，仅能看到正确的类型提示，完全看不到注释/描述。该问题在TS playground中也无法解决，这可能是TypeScript中JSDoc实现的限制，而非VSCode或项目配置问题。

1. 使用函数类型别名替代接口 #

函数类型别名的JSDoc注释更容易被IntelliSense识别，写法如下：

/**
 * 执行核心逻辑的函数
 * @param argv 命令行传入的参数
 * @param config 全局配置对象
 * @returns 无返回值
 */
type RunFunction = (
  argv: typeof import('./index.js').argv,
  config: typeof import('./index.js').config,
) => void;

2. 在JS文件中直接用JSDoc定义类型 #

如果不需要单独的TS类型文件，也可以直接在JS文件中通过@typedef和@callback定义类型并关联：

/**
 * @typedef {typeof import('./index.js').argv} ArgvType
 * @description 命令行传入的参数类型
 */

/**
 * @typedef {typeof import('./index.js').config} ConfigType
 * @description 全局配置对象类型
 */

/**
 * @callback RunFunction
 * @param {ArgvType} argv 命令行传入的参数
 * @param {ConfigType} config 全局配置对象
 * @returns {void}
 */

/** @type {RunFunction} */
exports.run = function(argv, config) {
  // 函数实现
};

3. 优化接口写法（备选） #

如果必须使用接口，可以尝试给接口本身添加描述，并在调用签名上补充完整注释，部分场景下TS会正确识别：

/**
 * 执行核心逻辑的函数接口
 */
interface RunFunction {
  /**
   * 执行具体业务逻辑
   * @param argv 命令行传入的参数
   * @param config 全局配置对象
   * @returns 无返回值
   */
  (
    argv: typeof import('./index.js').argv,
    config: typeof import('./index.js').config,
  ): void;
}

另外需要注意：如果typeof import('./index.js').argv这类动态导入的类型本身没有清晰的JSDoc注释，建议显式声明其结构（比如在TS类型文件中定义Argv和Config的具体接口并添加注释），避免TS无法解析深层的注释信息。

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