如何使用 JSDoc 记录 useState 挂钩？答案

【问题标题】：How do I document useState hooks with JSDoc?如何使用 JSDoc 记录 useState 挂钩？
【发布时间】：2023-03-23 05:42:01
【问题描述】：

我正在尝试使用 JSDoc 来记录我的反应状态钩子的解构部分，例如：

const [referenceState, setReferenceState] = useState(null);

这里，referenceState 是 Object 类型，setReferenceState 需要一个 Object。

根据网上的一些信息，我正在尝试做一些事情：

/**
* @param {Object} stateToSet
* @returns {GenericArray} current state and function to change value
*/
const [referenceState, setReferenceState] = useState(null);

但这不会产生任何东西..

有人可以帮我记录referenceState和setReferenceState吗？

【问题讨论】：

referenceState 是什么类型？一个东西？ setReferenceState 期望并返回什么参数？
@BrettZamir 抱歉，我没有添加这些细节。我已经编辑了这个问题。你是对的，referenceState 是一个对象，而setReferenceState 需要一个对象。

标签： javascript jsdoc

【解决方案1】：

我觉得你可以试试这个方法：

/**
 * @typedef {Object} ReferenceState
 */

/**
 * @callback ReferenceStateSetter
 * @param {ReferenceState} state
 * @returns {void}
 */

/**
 * @namespace {Object}
 * @property {ReferenceState} 0
 * @property {ReferenceStateSetter} 1 
 */
const [referenceState, setReferenceState] = useState(null);

或者，为了避免记录立即解构的数组，但受益于在末尾添加一些缩进更改：

/**
 * @typedef {Object} ReferenceState
 */

/**
 * @callback ReferenceStateSetter
 * @param {ReferenceState} state
 * @returns {void}
 */

const [
    /**
     * @type {ReferenceState}
     */
    referenceState,

    /**
     * @type {ReferenceStateSetter}
     */
    setReferenceState
] = useState(null);

如果您不想拥有ReferenceState 的文档，您可以去掉它的@typedef 并将对它的引用替换为Object，但我认为拥有文档更清晰。

上面的

void 是一种更简单的方式，可以说没有什么特别的（即undefined）被返回——如果这是 setter 返回的内容。如果它只返回undefined，某些项目只会删除@returns，但我喜欢添加它以显示返回值已知为undefined，而不仅仅是无证。

【讨论】：

【解决方案2】：

在webstorm中，你可以这样写（我没有在其他编辑器中测试过）：

const [state, setState] = useState(/** @type {{name: string, age: number?}} */null)

或

/**
 * @typedef People
 * @property {string} name
 * @property {number} [age]
 */

//........

const [state, setState] = useState(/** @type {People} */null)

【讨论】：

这也适用于 vscode

【解决方案3】：

作为替代方案，变量可以在解构之前声明并像往常一样使用 JSDoc 进行注释。

/**
* Current state.
* @type {Object}
*/
let referenceState;
/**
* Current state setter.
* @type {Function}
* @param {any} state updated state value.
* @returns void
*/
let setReferenceState;
[referenceState, setReferenceState] = useState(null);

【讨论】：