feat: API 文档的手动补全

[xiaohuoni]

Description

如果当前组件库是在其他基础组件的基础上构建的，那么组件的类型定义一般会从之前的类型中继承扩展。这时候如果原有的组件库中没有添加API的注释，在文档展示的时候，将会出现大片的空白描述。如果重新自定义，那API的变化又无法跟上旧项目的升级迭代。

如，原始库 antd-mobile 中定义类型

export interface ButtonProps extends ButtonPropsType {
    prefixCls?: string;
    className?: string;
    role?: string;
    inline?: boolean;
    icon?: React.ReactNode;
    activeClassName?: string;
    activeStyle?: boolean | React.CSSProperties;
    style?: React.CSSProperties;
    onClick?: React.MouseEventHandler<HTMLAnchorElement>;
}

新建的库中定义类型

export interface DemoPropsType extends ButtonProps {
  /**
   * 可以这样写属性描述
   * @description       也可以显式加上描述名
   * @description.en-US 还支持不同的 locale 后缀来实现多语言描述
   * @default           支持定义默认值
   */
  onClick?: (e?: React.SyntheticEvent) => void;
}

最终渲染效果

Solution

期望的效果是能够手动补全描述，类型定义和默认值又保持原有组件库的定义。

可能的解决方法是

<API supply="./supply.json"></API>

{
    "default": [
      {
        "identifier": "prefixCls",
        "description": "这里是对 prefixCls 的补充",
        "description.en-US": "这里是对 prefixCls 的多语言描述",
        "default": "支持定义默认值"
      },
      ...
    ]
 }

supply.json 将会与 .umi/dumi/apis.json 合并。

如果 <API> 中的 supply 没有指定，可以与 src 的处理类似，使用同目录下的 supply.json 文件来作为补充。

疑问

感觉这么处理，文档维护会变得很复杂，也很难懂。不知道还有没有其他更加优雅的方案实现。比如给 antd-mobile 的类型定义都加上注释之类的？

[PeachScript]

之前的设想是，继承来的属性可以自己复写加注解，比如：

interface DemoProps {
  /**
   * 点击事件
   */
  onClick: ButtonProps['onClick'];
}

单独维护一份 JSON 比较容易 outdated

[xiaohuoni]

继承它，又用原定义复写它，感觉逻辑也挺怪的。

[xiaohuoni]

之前的设想是，继承来的属性可以自己复写加注解，比如：

interface DemoProps {
  /**
   * 点击事件
   */
  onClick: ButtonProps['onClick'];
}

单独维护一份 JSON 比较容易 outdated

使用这种方式书写了。感觉很枯燥。仅仅为了加上两行注释，体验上还不如直接写 table

[ch11ry]

请问这个 API 空白的问题目前有解决的办法了吗？ 比如有办法可以直接不显示继承的属性？ @PeachScript