Skip to content

组件 demo 和 api 文档编写规范

Kagol edited this page Dec 4, 2023 · 2 revisions

把自己当成小白用户,去体验,去优化。

API 文档:

  1. api 表格列字段统一 props / events / slots / methods
  2. 描述格式美化
  3. props 类型明确、事件参数类型明确、插槽数据类型明确、method 参数和返回值类型明确
  4. api 顺序按照首字母顺序排列,符合预期
  5. demo 跳转正确
  6. 消除错别字、重复、不对应的内容

Demo 文档:

  1. demo 设计要合理,按特性进行分类,相同的特性整合到一个 demo 中,适当地通过在 demo 中增加切换功能
  2. demo 说明需要清晰
  3. demo 代码去除多余的干扰代码、重复代码
  4. 整改不符合规范的 demo 示例代码,不写行内样式
  5. 按照使用频率高低来设置 demo 顺序,确保高频使用的特性 demo 放前面
  6. 测试 playground 跳转后是否正常
  7. demo标题命名规则统一
  8. 识别组件问题
  9. Options / Composition 写法的 demo 都应该有
  10. 语句末尾(除了 api 部分,即表格的中文描述不需要加)都需要增加句号 。
  11. 中英文混杂的部分英文两边需要增加一个空格
  12. demo 中的内容不能太拥挤

其他:

  1. 组件 demo 里有一些是 设置 xxx 或者 xxx 设置 的,可直接写成  xxx  ,不要加 设置 的字样,因为 demo 就是演示各种功能和 api 的设置/配置。比如 设置尺寸 改成  尺寸
  2. api 的默认值为空可以用 --
  3. ...(欢迎补充)