TypeScript 到 JSDoc：全局/接口

Question

我目前正在使用 JSDoc 将项目从 TypeScript 转换为 JavaScript。我正在尝试使用 JSDoc 执行以下操作：

declare global {
  namespace jest {
    interface Matchers<R> {
        toBeTheSameAsRemote: (expected: string) => CustomMatcherResult;
    }
  }
}

到目前为止我已经想出了这个：

/**
 * @namespace jest
 */
/**
 * @interface Matchers
 * @memberof jest
 */

不幸的是，https://jsdoc.app/tags-interface.html中的示例没有帮助。

Answer 1

在我的纯 JavaScript 项目中，我使用这些 JSDoc 实体来使 WebStorm 识别扩展（我将它们放在

expect.extend

调用之前）：

/**
 * @function JestMatchers#toBeTheSameAsRemote
 */
/**
 * @function Matchers#toBeTheSameAsRemote
 */

第一个是

expect(...).toBeTheSameAsRemote()

需要的，第二个是

expect(...)

.not.

toBeTheSameAsRemote()

工作的。 如果您的匹配器有自己的参数，您可以在此处使用

@param

标签记录它们 - 不幸的是，您需要复制它们。

Answer 2

此问题的解决方法是使用打字稿定义文件按照 VsCode 文档中的建议

例如，您可以添加一个

jest/jest.d.ts

文件：

import { CustomMatcherResult } from 'jest';

declare module 'expect' {
  namespace jest {
    interface JestMatchers<R> {
      toBeTheSameAsRemote(expected: string): CustomMatcherResult;
    }

    interface Matchers<R> {
      toBeTheSameAsRemote<T>(expected: string): CustomMatcherResult;
    }
  }
}

然后将其与项目根目录中的

jsconfig.json

连接起来

{
  ...
  "include": ["jest/jest.d.ts"]
  ...
}

它不是纯jsdoc，但它允许您在类型检查时将代码保持为纯js。

d.ts

文件不会改变 JavaScript 的计算方式，它们仅用于提供更好的 JavaScript 语言支持。

该文档适用于 VsCode，但适用于其他编辑器中的 TypeScript 语言服务器。