javascript - How to document function custom types in JSDoc (or TypeScript?) and reference them so VSCode IntelliSense works - S

admin管理员组

文章数量:1415653

I am trying to document custom function types as part of an object, any help would be greatly appreciated:

Context of the problem

Here is a simple object declaration with some function properties (addCoordinate, addCoordinateOne, addCoordinateTwo) which we will go over as 3 exhibits, and why none of these work.

/**
 * @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 = {}

Exhibit A

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

This works fully, but isn't reusable like I need.

Exhibit B

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

This sort of works, as it detects the custom function type. But it doesn't parse parameters properly. I made sure to follow the documentation for the @typedef tag: /tags-typedef.html

Exhibit C

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

This fails pletely. Despite being the remended approach by JSDoc's @function documentation. /tags-function.html

The Question

Is there any way I could get Exhibit B or C working like Exhibit A?

I am trying to document custom function types as part of an object, any help would be greatly appreciated:

Context of the problem

Here is a simple object declaration with some function properties (addCoordinate, addCoordinateOne, addCoordinateTwo) which we will go over as 3 exhibits, and why none of these work.

/**
 * @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 = {}

Exhibit A

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

This works fully, but isn't reusable like I need.

Exhibit B

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

This sort of works, as it detects the custom function type. But it doesn't parse parameters properly. I made sure to follow the documentation for the @typedef tag: https://jsdoc.app/tags-typedef.html

Exhibit C

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

This fails pletely. Despite being the remended approach by JSDoc's @function documentation. https://jsdoc.app/tags-function.html

The Question

Is there any way I could get Exhibit B or C working like Exhibit A?

• javascript
• typescript
• visual-studio-code
• jsdoc

Share Improve this question Follow asked Apr 19, 2022 at 14:16 sgarcia.devsgarcia.dev 6,2001414 gold badges5151 silver badges8484 bronze badges

Add a ment  | 

1 Answer 1

Sorted by: Reset to default 6

You can change Exhibit A to a typedef:

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

Edit: Or more verbosely, you can use the @callback tag:

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

Then reuse as needed:

/**
 * @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
 */

Result:

If using the shorthand syntax, no paramater descriptions are available.

If using the @callback syntax, descriptions are provided for each paramater:

本文标签：