如何在 JSDoc（或 TypeScript？）中记录函数自定义类型并引用它们以便 VSCode IntelliSense 工作

Question

我正在尝试将自定义函数类型记录为对象的一部分，如有任何帮助，我们将不胜感激：

问题的背景

这是一个简单的对象声明，其中包含一些函数属性（addCoordinate、addCoordinateOne、addCoordinateTwo），我们将作为 3 个展品进行介绍，以及为什么 none 这些功能有效。

/**
 * @typedef {Object} Point
 * @property {number} x - The X Coordinate
 * @property {number} y - The Y Coordinate
 */

/**
 * @typedef {Object} Shape
 * @property {Point} startCoordinate - the starting coordinate
 * @property {Point[]} coordinates - An array of point coordinates
 * @property {(x:string, y:string) => void} addCoordinate - Updates the point
 * @property {addCoordinateOne} addCoordinateOne - Updates the point
 * @property {addCoordinateTwo} addCoordinateTwo - Updates the point
 */

/** @type {Shape} */
const square = {}

图表 A

@property {(x:string, y:string) => void} addCoordinate - Updates the point

这完全可以工作，但不能像我需要的那样重复使用。

图表 B

/**
 * @typedef {Function} addCoordinateOne
 * @param {string} X
 * @param {string} Y
 */

这种类型的有效，因为它检测自定义函数类型。但它没有正确解析参数。我确保遵循 @typedef 标签的文档： https://jsdoc.app/tags-typedef.html

图表 C

/**
 * @function addCoordinateTwo
 * @param {string} X
 * @param {string} Y
 */

这完全失败了。尽管这是 JSDoc 的 @function 文档推荐的方法。 https://jsdoc.app/tags-function.html

问题

有什么方法可以让图表 B 或 C 像图表 A 一样工作？

Answer 1

您可以将图表 A 更改为 typedef：

/** @typedef {(x:string, y:string) => void} addCoordinate */

编辑：或者更详细地说，您可以使用 @callback 标签：

/** 
 * @callback addCoord
 * @param {number} x - The x coordinate
 * @param {number} y - The y coordinate 
 * @returns {void}
 */

然后根据需要重复使用：

/**
 * @typedef {Object} Point
 * @property {number} x - The X Coordinate
 * @property {number} y - The Y Coordinate
 */

/**
 * @typedef {Object} Shape
 * @property {Point} startCoordinate - the starting coordinate
 * @property {Point[]} coordinates - An array of point coordinates
 * @property {addCoordinate} addCoordinate - Updates the point
 * @property {addCoordinate} addCoordinateOne - Updates the point
 * @property {addCoordinate} addCoordinateTwo - Updates the point
 */

结果：

如果使用 shorthand 语法，则没有可用的参数说明。

如果使用 @callback 语法，将为每个参数提供说明：