doc: add more docs

config/config.ts

@@ -8,47 +8,115 @@ import routes from './routes';
 const { REACT_APP_ENV } = process.env;
 
 export default defineConfig({
+  /**
+   * @name 开启 hash 模式
+   * @description 让 build 之后的产物包含 hash 后缀。通常用于增量发布和避免浏览器加载缓存。
+   * @doc https://umijs.org/docs/api/config#hash
+   */
   hash: true,
-  antd: {},
-  request: {},
-  initialState: {},
-  model: {},
-  layout: {
-    // https://umijs.org/zh-CN/plugins/plugin-layout
-    locale: true,
-    siderWidth: 208,
-    ...defaultSettings,
-  },
-  // https://umijs.org/zh-CN/plugins/plugin-locale
-  locale: {
-    // default zh-CN
-    default: 'zh-CN',
-    antd: true,
-    // default true, when it is true, will use `navigator.language` overwrite default
-    baseNavigator: true,
-  },
 
+  /**
+   * @name 兼容性设置
+   * @description 设置 ie11 不一定完美兼容，需要检查自己使用的所有以来
+   * @doc https://umijs.org/docs/api/config#targets
+   */
   targets: {
     ie: 11,
   },
+  /**
+   * @name 路由的配置，不在路由中引入的文件不会编译
+   * @description 只支持 path，component，routes，redirect，wrappers，title 的配置
+   * @doc https://umijs.org/docs/guides/routes
+   */
   // umi routes: https://umijs.org/docs/routing
   routes,
-  access: {},
+  /**
-  // Theme for antd: https://ant.design/docs/react/customize-theme-cn
+   * @name 主题的配置
+   * @description 虽然叫主题，但是其实只是 less 的变量设置
+   * @doc antd的主题设置 https://ant.design/docs/react/customize-theme-cn
+   * @doc umi 的theme 配置 https://umijs.org/docs/api/config#theme
+   */
   theme: {
     // 如果不想要 configProvide 动态设置主题需要把这个设置为 default
     // 只有设置为 variable， 才能使用 configProvide 动态设置主色调
-    // https://ant.design/docs/react/customize-theme-variable-cn
     'root-entry-name': 'variable',
   },
+  /**
+   * @name moment 的国际化配置
+   * @description 如果对国际化没有要求，打开之后能减少js的包大小
+   * @doc https://umijs.org/docs/api/config#ignoremomentlocale
+   */
   ignoreMomentLocale: true,
+  /**
+   * @name 代理配置
+   * @description 可以让你的本地服务器代理到你的服务器上，这样你就可以访问服务器的数据了
+   * @see 要注意以下 代理只能在本地开发时使用，build 之后就无法使用了。
+   * @doc 代理介绍 https://umijs.org/docs/guides/proxy
+   * @doc 代理配置 https://umijs.org/docs/api/config#proxy
+   */
   proxy: proxy[REACT_APP_ENV || 'dev'],
-  manifest: {
+  /**
-    basePath: '/',
+   * @name 快速热更新配置
-  },
+   * @description 一个不错的热更新组件，更新时可以保留 state
-  // Fast Refresh 热更新
+   */
   fastRefresh: true,
+  //============== 以下都是max的插件配置 ===============
+  /**
+   * @name 数据流插件
+   * @@doc https://umijs.org/docs/max/data-flow
+   */
+  model: {},
+  /**
+   * 一个全局的初始数据流，可以用它在插件之间共享数据
+   * @description 可以用来存放一些全局的数据，比如用户信息，或者一些全局的状态，全局初始状态在整个 Umi 项目的最开始创建。
+   * @doc https://umijs.org/docs/max/data-flow#%E5%85%A8%E5%B1%80%E5%88%9D%E5%A7%8B%E7%8A%B6%E6%80%81
+   */
+  initialState: {},
+  /**
+   * @name layout 插件
+   * @doc https://umijs.org/docs/max/layout-menu
+   */
+  layout: {
+    locale: true,
+    siderWidth: 208,
+    ...defaultSettings,
+  },
+  /**
+   * @name 国际化插件
+   * @doc https://umijs.org/docs/max/i18n
+   */
+  locale: {
+    // default zh-CN
+    default: 'zh-CN',
+    antd: true,
+    // default true, when it is true, will use `navigator.language` overwrite default
+    baseNavigator: true,
+  },
+  /**
+   * @name antd 插件
+   * @description 内置了 babel import 插件
+   * @doc https://umijs.org/docs/max/antd#antd
+   */
+  antd: {},
+  /**
+   * @name 网络请求配置
+   * @description 它基于 axios 和 ahooks 的 useRequest 提供了一套统一的网络请求和错误处理方案。
+   * @doc https://umijs.org/docs/max/request
+   */
+  request: {},
+  /**
+   * @name 权限插件
+   * @description 基于 initialState 的权限插件，必须先打开 initialState
+   * @doc https://umijs.org/docs/max/access
+   */
+  access: {},
+  //================ pro 插件配置 =================
   presets: ['umi-presets-pro'],
+  /**
+   * @name openAPI 插件的配置
+   * @description 基于 openapi 的规范生成serve 和mock，能减少很多样板代码
+   * @doc https://pro.ant.design/zh-cn/docs/openapi/
+   */
   openAPI: [
     {
       requestLibPath: "import { request } from '@umijs/max'",

config/defaultSettings.ts

@@ -1,5 +1,8 @@
 import { Settings as LayoutSettings } from '@ant-design/pro-components';
 
+/**
+ * @name
+ */
 const Settings: LayoutSettings & {
   pwa?: boolean;
   logo?: string;

config/routes.ts

@@ -1,4 +1,14 @@
-export default [
+/**
+ * @name umi 的路由配置
+ * @description 只支持 path,component,routes,redirect,wrappers,title 的配置
+ * @param path  path 只支持两种占位符配置，第一种是动态参数 :id 的形式，第二种是 * 通配符，通配符只能出现路由字符串的最后。
+ * @param component 配置 location 和 path 匹配后用于渲染的 React 组件路径。可以是绝对路径，也可以是相对路径，如果是相对路径，会从 src/pages 开始找起。
+ * @param routes 配置子路由，通常在需要为多个路径增加 layout 组件时使用。
+ * @param redirect 配置路由跳转
+ * @param wrappers 配置路由组件的包装组件，通过包装组件可以为当前的路由组件组合进更多的功能。 比如，可以用于路由级别的权限校验
+ * @doc https://umijs.org/docs/guides/routes
+ */
+export default [
   {
     path: '/user',
     layout: false,