jsdoc：从其他模块引用 typedef-ed 类型

Question

假设我在 js 模块中有一个 typedef 类型

// somewhere/foo.js
/**
 * @module
 */ 
/**
 * @typedef Foo
 * @type {object}
 * property {string} bar - some property
 */

是否可以在另一个模块中引用此类型，以便在 jsdoc 生成的 HTML 页面中，该类型显示为 link 到 typedef-ed 模块？

我尝试了这个的变体，但似乎没有任何效果...

// somewhere_else/bar.js
/**
 * @module
 */
/**
 * @param {somewhere/foo/Foo} foo - some param
 */
export default function doStuff(foo) {
  ...
}

Answer 1

这对我有用...

// somewhere/foo.js
/**
 * @module foo
 */
/**
 * @typedef module:foo.Foo
 * @type {object}
 * @property {string} bar - some property
 */

和...

// somewhere_else/bar.js
/// <reference path="foo.js" />
/**
 * @module bar
 */
/**
 * @param {module:foo.Foo} foo - some param
 */
function doStuff(foo) {
  //...
};

Answer 2

以上答案在搜索结果中排名靠前，因此我记录了对我有用的答案，以防它能帮助处于类似情况的人。

我在所有模块上使用 Visual Studio 节点项目代码 // @ts-check。在 module: 语法上使用上述语法会出现问题。此外，代码帮助无法正常工作。我花了一段时间，但答案很简单

如果我在模块 myModule 中有 typedef myTypedef 那么在我需要的第二个模块中 myModule
mm = require(myModule)
我可以使用类似
的东西 /** @param {mm.myTypedef} myParamName */

Answer 3

以上两种方法我都试过了

首先，在 @typedef module:foo.Foo 的情况下，VSCode 将 Foo 在与 any 相同的文件中使用。我认为这是不可接受的。

其次，使用ES6导入时出现以下问题：

import foo from 'foo'

/** @param {foo.Foo} a - Error Foo does not exist on foo */

另一方面，即使使用 JSDoc 模块语法，VSCode 也能识别 import { Foo } from 'foo' 而无需 ：

/**
 * @module bar
 */

此外，我还能够在导入类型上引用属性，即：

import { Foo } from 'foo'

/** @param {Foo['bar']} bar */

备注

该项目使用 Babel 并假设编译代码使用类型导入在没有转译器的情况下不可行。

Answer 4

许多库从它们的根文件中导出类型，要访问 typedef 中的类型，请将您的导入更改为使用 import * as 格式。

例如：

import * as testingLibrary from '@testing-library/react';


/** 
 * @returns {testingLibrary.RenderResult}
 */
export function myCustomRender() { }

Answer 5

我正在使用 vscode-powertools script which provides access to vscode 模块 在运行时 （而不是在编辑时通过本地 [=13] 供 VSCode 使用=]).

如果我尝试使用通常的 jsdoc 导入类型 import

//@ts-check
/** @typedef {import('c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode').TextEditor} TextEditor */

我会收到 File is not a module 错误：

File 'C:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode/vscode.d.ts' is not a module. ts(2306)

所以这是我用来对那种脚本进行类型检查的技巧：

//@ts-check
/// <reference types="c:/Users/USERNAME/.vscode/extensions/ego-digital.vscode-powertools-0.64.0/node_modules/vscode" /> 

// Allows us to reference the `vscode` module with jsdoc `@type`
async function vscodeⁱ() {if (1 == 1) return null; return import ('vscode')}

exports.execute = async (args) => {
  // Allows us to reference the `vscode` module with jsdoc `@type`
  const vscode = await vscodeⁱ()

  /** @type {vscode} */
  const vs = args.require ('vscode')

  // NB: The following code is fully typed in VSCode
  const windowᵛ = vs.window
  const editorᵛ = windowᵛ.activeTextEditor
  const start = editorᵛ.selection.start
}

Answer 6

TypeScript 不支持 module 语法，所以如果你来到这里假设它可以工作，我还没有能够让上面的解决方案工作。

要使其与 TypeScript 一起使用，请使用 Import Types

对于 OP，我的做法是

// foo.d.ts
export type Foo = {
  /**
   * some property
   */
  bar: string,
};

然后在JS模块中引用为

/**
 * @typedef { import("./foo").Foo } Foo
 */

/**
 * @param {Foo} foo - some param
 */
export default function doStuff(foo) {
  ...
}

您可以通过将以下内容添加到文件的开头来更严格地验证单个文件是否正常工作。这将在特定文件的 Visual Studio 代码中启用打字稿检查，以帮助您为将来迁移到打字稿做好准备。

// @ts-check

jsdoc：从其他模块引用 typedef-ed 类型

jsdoc : reference typedef-ed type from other module

jsdoc

jsdoc3