如何用TypeDoc为useState调用加文档？返回状态缺描述

我有一个带文档注释的自定义Hook useDrag，它返回一个状态值和多个函数。TypeDoc能正确生成各函数的文档，但返回的isDragging状态仅显示boolean类型，缺少对应的描述信息。原代码如下：

export default function useDrag(data: json | string, title: string) {
    /** Состояние, определяющее перемещается ли элемент в данный момент (drag) */
    const [isDragging, setDragging] = useState<boolean>(false)

    /**
     * Функция переопределяет базовые реакции на drag event
     * @param e
     */
    function onDragOver(e: React.DragEvent<HTMLDivElement>) {
        e.preventDefault()
    }

    /**
     * Функция устанавливает состояние isDragging и устанаваливает данные в dataTransfer
     * @param e
     */
    function onDragStart(e: React.DragEvent<HTMLDivElement>) {
        setDragging(true)
        e.dataTransfer.setData('BlankJSONElement', JSON.stringify({
            data: data,
            title: title
        }))
    }

    /**
     * Функция устанавливает состояние isDragging и устанаваливает данные в dataTransfer
     * @param e
     */
    function onDragEnd(e: React.DragEvent<HTMLDivElement>) {
        setDragging(false)
    }

    return {
        isDragging,
        onDragOver,
        onDragStart,
        onDragEnd
    }
}

方法1：直接为返回对象的属性添加注释 #

在return语句中，给isDragging属性直接添加JSDoc注释，TypeDoc会识别该注释并生成对应的文档描述：

export default function useDrag(data: json | string, title: string) {
    const [isDragging, setDragging] = useState<boolean>(false)

    // 函数部分代码保持不变

    return {
        /** Состояние, определяющее перемещается ли элемент в данный момент (drag) */
        isDragging,
        onDragOver,
        onDragStart,
        onDragEnd
    }
}

方法2：定义返回类型接口并添加注释 #

先定义包含所有返回值的接口，为接口的每个属性添加注释，再让Hook明确返回该接口类型。这种方式更适合返回结构复杂的Hook，也能让类型定义更清晰：

/**
 * useDrag Hook的返回类型
 */
interface UseDragReturn {
    /** Состояние, определяющее перемещается ли элемент в данный момент (drag) */
    isDragging: boolean;
    /** Функция переопределяет базовые реакции на drag event */
    onDragOver: (e: React.DragEvent<HTMLDivElement>) => void;
    /** Функция устанавливает состояние isDragging и устанаваливает данные в dataTransfer */
    onDragStart: (e: React.DragEvent<HTMLDivElement>) => void;
    /** Функция устанавливает состояние isDragging */
    onDragEnd: (e: React.DragEvent<HTMLDivElement>) => void;
}

export default function useDrag(data: json | string, title: string): UseDragReturn {
    const [isDragging, setDragging] = useState<boolean>(false)

    // 函数部分代码保持不变

    return {
        isDragging,
        onDragOver,
        onDragStart,
        onDragEnd
    }
}

以上两种方法都能让TypeDoc正确读取isDragging的描述信息，生成完整的文档。方法1更简洁，适合简单的返回结构；方法2更利于维护，尤其当Hook返回内容较多或需要复用类型时。

内容的提问来源于stack exchange，提问作者Александр Генералов