JSDoc typedef在一个单独的文件中

Question

我可以在单独的文件中定义所有自定义类型(例如types.jsdoc),以便它们可以在整个应用程序中重用吗？什么是正确的方法呢？

/**
 * 2d coordinates.
 * @typedef {Object} Coordinates
 * @property {Number} x - Coordinate x.
 * @property {Number} y - Coordinate y.
 */

Answer 1

您可以在模块中定义类型（例如。typedefs.js）。该模块包含您的 JSDoc 类型定义，并且可以简单地导出未使用的属性。

// typedefs.js
/**
 * @typdef foo
 * @property {string} bar
 */

// etc.

exports.unused = {};

要使用它，请在需要引用这些 typdef 的位置导入模块：

const typedefs = require("./typedefs");
/** @type {typedefs.foo} */
const fb = { bar: "hello" };

您可能希望注释typedefs.js为 a@module或@namespace。因为我正在使用“tsd-jsdoc”来生成一个types.d.ts文件，并且由于 TypeScript 现在解释模块与命名空间的方式，我将我的typedefs.js文件注释为 a@namespace并将每个 typedef 记录为该命名空间的成员：

/**
 * @namespace typedefs
 */

/**
 * @typedef foo
 * @property {string} bar
 * @memberof typdefs
 */

希望有帮助。

Answer 2

这是一个 TypeScript 风格的 JSDoc 特定答案，但我成功地使用三斜线指令从另一个文件“导入”所有类型。这样做的优点是实际上不会添加未使用的东西import，这会扰乱短绒和打包器。

我将我的共享类型放在一个文件中，typedefs.js如下所示：

// typedefs.js
/**
 * @typedef {Object} Foo
 * @property {string} bar
 */

/**
 * @typedef {Object} Baz
 * @property {number} buzz
 */

然后/// <reference path="typedefs.js" />在其他文件中使用来访问这样的共享类型：

// randomThing.js
/// <reference path="typedefs.js" />

/**
 * Turn a Foo into a Baz
 *
 * @param {Foo} a
 * @return {Baz}
export function (a) {
  return { buzz: a.bar.length };
}

但棘手的是，现在typedefs.js只是在评论中被引用，像 rollup 这样的打包器完全错过了它。所以我将它与我的旧的相结合，它consts.js导出一些常量并至少在一个地方导入。这样 typedef 仍然包含在汇总输出中。

我希望其他人觉得这有帮助。

ps rollup 将完全排除纯 JSDoctypedefs.js文件 _即使您import './typedefs.js'因为摇树而拥有！必须运行汇总--no-treeshake以将这些评论保留在汇总输出中。

Answer 3

在 vscode 中，该import('./path/to/types.js').def标签工作得很好。

例如
types.js

/**
 * @typedef {Object} connection
 * @property {String} id
 * @property {Number} pingRetries
 * @property {(data:Object) => void} sendJSON
 */
exports.unused = {};

和someFile.js

/**
 * @param {import('./types').connection} param
 */
const someFunc = (param) => {}

另请注意，文件中的exports.unused = {}是必需的types.js，否则自动导入import('./types')将无法工作，您可能必须自己键入。

Answer 4

我通常在我的项目中做类似的事情，不同之处在于我使用扩展名.js来命名文件。Webstorm 工作完美，能够很好地检查类型和自动完成。它不会识别扩展名（我刚刚检查过），因此即使文件不包含任何代码语句，也要.jsdoc坚持使用。.js