如何为透传Props的React组件编写TSDoc文档？

针对你遇到的按钮变体组件需要继承BaseButton的TSDoc、同时在VSCode中正确显示Props提示的问题，这里有几个实用的解决办法：

1. 用TSDoc的@inheritDoc标签直接继承文档 #

TSDoc原生支持@inheritDoc标签，可以直接复用BaseButton的参数说明，不用手动重复写@param，还能避免lint报错。只需要在变体组件的注释里加上指向BaseButton的继承声明：

/**
 * 创建一个默认type=button的按钮组件，支持点击事件处理
 *
 * @inheritDoc BaseButton
 * @param onClick 按钮点击事件处理器（可选）
 * @returns Button组件
 */
export const Button = ({ onClick, children, ...props }: TypedButtonProps): JSX.Element => {
  // ... 组件逻辑
}

这样VSCode的智能提示会自动加载BaseButton里的accent、disabled等参数的说明，同时你可以单独补充变体组件特有的参数（比如这里的onClick）。

2. 优化类型定义，让TypeScript自动推导Props提示 #

确保你的TypedButtonProps类型正确继承了BaseButton的Props（除了type），这样TypeScript本身就能在VSCode中给出完整的Props提示，结合@inheritDoc就能做到文档和类型提示的统一：

// 调整TypedButtonProps的定义，更清晰地表达继承关系
type TypedButtonProps = PropsWithChildren<Omit<ButtonProps, 'type'>>;

这里的Omit<ButtonProps, 'type'>明确排除了type字段，同时保留了其他所有BaseButton的Props，TypeScript会自动识别这些字段并在VSCode中显示。

3. 处理可能的lint报错 #

如果你的lint规则（比如@typescript-eslint/no-unused-vars或者TSDoc相关规则）因为@inheritDoc或者未显式声明的参数报错，可以做以下调整：

• 对于ESLint，在组件文件顶部添加// eslint-disable-next-line @typescript-eslint/no-unused-vars（如果是特定参数的问题），或者在ESLint配置中调整tsdoc/syntax规则允许@inheritDoc。
• 确保你的TSDoc解析器（比如typedoc）支持@inheritDoc标签，这样注释不会被判定为无效。

修改后的完整代码示例 #

// 从React中复用按钮元素的Props
import { ButtonHTMLAttributes, PropsWithChildren, useCallback, MouseEvent } from 'react';
import clsx from 'clsx';
import styles from './Button.module.css';

// 假设Accented是已定义的接口
interface Accented {
  accent?: string;
}

type BaseButtonProps = Pick<ButtonHTMLAttributes<HTMLButtonElement>, 'disabled' | 'onClick' | 'type'>;

// 定义所有按钮类型的基础接口
export interface ButtonProps extends Accented, BaseButtonProps {}

/**
 * 创建无默认配置的基础按钮组件
 *
 * @param accent UI主题色
 * @param disabled 是否禁用按钮
 * @param onClick 点击事件处理器
 * @returns 基础按钮组件
 */
const BaseButton = ({ accent, children, ...props }: PropsWithChildren<ButtonProps>): JSX.Element =>
  <button className={clsx('btn', styles.button, accent && styles[accent])} {...props}>{children}</button>

// 预定义排除type的按钮Props类型
type TypedButtonProps = PropsWithChildren<Omit<ButtonProps, 'type'>>;

/**
 * 创建默认type=submit的提交按钮组件
 *
 * @inheritDoc BaseButton
 * @returns SubmitButton组件
 */
export const SubmitButton = ({ children, ...props }: Omit<TypedButtonProps, 'onClick'>): JSX.Element =>
  <BaseButton type='submit' {...props}>{children}</BaseButton>

/**
 * 创建默认type=button的按钮组件，支持点击事件处理
 *
 * @inheritDoc BaseButton
 * @param onClick 按钮点击事件处理器（可选）
 * @returns Button组件
 */
export const Button = ({ onClick, children, ...props }: TypedButtonProps): JSX.Element => {
  const onButtonClick = useCallback((event: MouseEvent<HTMLButtonElement>): void => {
    event.preventDefault()
    event.stopPropagation()

    onClick?.(event)
  }, [onClick])

  return <BaseButton onClick={onButtonClick} type='button' {...props}>{children}</BaseButton>
}

这样调整后，VSCode的智能提示会显示所有继承自BaseButton的Props说明，同时不会出现lint报错，也不用重复编写相同的@param注释。

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