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 typedef，并且可以简单地导出未使用的属性。

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

// etc.

exports.unused = {};
// or export {};

要使用它，请在需要引用这些 typedef 的地方导入模块：

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

您可能希望将

typedefs.js

注释为

@module

或

@namespace

。因为我正在使用“tsd-jsdoc”生成

types.d.ts

文件，并且由于TypeScript现在解释模块与命名空间的方式，我将我的

typedefs.js

文件注释为

@namespace

并将每个typedef记录为该名称空间的成员：

/**
 * @namespace typedefs
 */

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

希望有帮助。

Answer 2

This is a TypeScript-flavored JSDoc specific answer,但我成功地使用了三斜杠指令从另一个文件“导入”所有类型。这样做的好处是实际上不会添加未使用的

import

，这可能会扰乱 linters 和 bundlers.

我将我的共享类型放在一个名为

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 仍然包含在汇总输出中。

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

附注rollup 将完全排除纯 JSDoc

typedefs.js

文件 _即使你有

import './typedefs.js'

因为 tree-shaking！必须使用

--no-treeshake

运行 rollup 以将这些评论保留在 rollup 输出中。

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文件中的

necessary

，否则

import('./types')

的自动导入将不起作用，您可能需要自己输入。

Answer 4

我刚刚尝试使用 VSCode，只有在编辑器中打开单独的文件时它才有效。如果不是，则外部 typedef 的类型为 any

Answer 5

我通常在我的项目中做类似的事情，不同之处在于我使用扩展名

.js

来命名文件。 Webstorm 工作完美，能够检查类型并自动完成。它不会识别

.jsdoc

扩展名（我刚刚检查过），所以即使文件不包含任何代码语句，也要坚持

.js

。

Answer 6

我已经成功地在

typedefs.js

文件中创建我的类型并使用 ts/vscode

import(path/to/file).Foo

标签进行引用。 JSDoc 不支持这种开箱即用的语法，所以我建议也使用 jsdoc-tsimport-plugin 来解析你的文档。

例如：typedef.js：

/**
 * @typedef {Object} Foo
 * @property {string} id
 */

/**
 * @typedef {Object} Bar
 * @property {string[]} things
 */

// having to export an empty object here is annoying, 
// but required for vscode to pass on your types. 
export {};

coolFunction.js

/**
 * This function is super dope
 * @param {import('../typedef').Foo[]} foo - a foo
 * @return {import('../typedef').Bar[]} bar - an array of bars
 */

 export function (foo) {
    // do cool things
    return bar;
 }

我也在使用 tsd-jsdoc 创建一个

types.d.ts

文件，这个实现成功地创建了类型。我在使用类型文件声明

modules

和

namespaces

时遇到了麻烦——只是为所述模型创建独立的

typedefs

最适合我。