如何使用JSDoc记录React useState钩子的解构变量？

嘿，我明白你遇到的问题了——原来的JSDoc注释没有准确对应到解构出来的referenceState和setReferenceState，所以生成的文档不符合预期。下面给你两种实用的解决方案：

方法1：直接注释解构后的变量 #

这种方式简单直接，针对每个解构出来的变量单独添加类型注释：

import { useState } from 'react';

const MyComponent = () => {
  /**
   * 当前的引用状态，初始值为null
   * @type {Object | null}
   */
  /**
   * 更新引用状态的函数，接收一个Object类型的新状态作为参数
   * @type {(newState: Object) => void}
   */
  const [referenceState, setReferenceState] = useState(null);

  // 使用示例
  const handleUpdate = () => {
    setReferenceState({ id: 'ref-001', label: '示例引用' });
  };

  return <div>{referenceState?.label}</div>;
};

方法2：用@typedef定义状态结构（更推荐） #

如果你的Object有明确的属性结构，建议先定义一个类型别名，再用它来标注状态和setter函数，这样注释的可读性和工具提示的准确性都会更高：

import { useState } from 'react';

/**
 * 引用状态的结构定义
 * @typedef {Object} ReferenceState
 * @property {string} id - 引用的唯一标识
 * @property {string} label - 引用的显示文本
 */

const MyComponent = () => {
  /**
   * 引用状态及其更新函数
   * @type {[ReferenceState | null, (newState: ReferenceState) => void]}
   */
  const [referenceState, setReferenceState] = useState(null);

  // 或者结合React useState的泛型语法（JSDoc支持这种写法）
  // const [referenceState, setReferenceState] = useState<ReferenceState | null>(null);

  return <div>{referenceState?.label}</div>;
};

为什么原来的注释不生效？ #

你之前写的注释是针对自定义函数的@param和@returns，但这里我们是在使用React的useState钩子，它的返回值是一个包含状态和setter的数组。原来的注释没有关联到解构出来的变量，也没有准确描述useState的返回类型，所以工具无法生成正确的文档。

内容的提问来源于stack exchange，提问作者Abhinav Das