chore: add prettier-plugin-jsdoc (#28551)

components/_util/__tests__/getScrollNode.test.ts

@@ -1,6 +1,4 @@
-/**
+/** @jest-environment node */
- * @jest-environment node
- */
 import getScroll from '../getScroll';
 
 describe('getScroll node', () => {

components/_util/transButton.tsx

@@ -1,5 +1,6 @@
 /**
  * Wrap of sub component which need use as Button capacity (like Icon component).
+ *
  * This helps accessibility reader to tread as a interactive button to operation.
  */
 import * as React from 'react';

components/_util/type.ts

@@ -5,12 +5,10 @@ export const tuple = <T extends string[]>(...args: T) => args;
 export const tupleNum = <T extends number[]>(...args: T) => args;
 
 /**
- * https://stackoverflow.com/a/59187769
+ * https://stackoverflow.com/a/59187769 Extract the type of an element of an array/tuple without
- * Extract the type of an element of an array/tuple without performing indexing
+ * performing indexing
  */
 export type ElementOf<T> = T extends (infer E)[] ? E : T extends readonly (infer F)[] ? F : never;
 
-/**
+/** https://github.com/Microsoft/TypeScript/issues/29729 */
- * https://github.com/Microsoft/TypeScript/issues/29729
- */
 export type LiteralUnion<T extends U, U> = T | (U & {});

components/affix/index.tsx

@@ -19,9 +19,7 @@ function getDefaultTarget() {
 
 // Affix
 export interface AffixProps {
-  /**
+  /** 距离窗口顶部达到指定偏移量后触发 */
-   * 距离窗口顶部达到指定偏移量后触发
-   */
   offsetTop?: number;
   /** 距离窗口底部达到指定偏移量后触发 */
   offsetBottom?: number;

components/alert/index.tsx

@@ -17,9 +17,7 @@ import ErrorBoundary from './ErrorBoundary';
 import { replaceElement } from '../_util/reactNode';
 
 export interface AlertProps {
-  /**
+  /** Type of Alert styles, options:`success`, `info`, `warning`, `error` */
-   * Type of Alert styles, options:`success`, `info`, `warning`, `error`
-   */
   type?: 'success' | 'info' | 'warning' | 'error';
   /** Whether Alert can be closed */
   closable?: boolean;

components/avatar/avatar.tsx

@@ -22,7 +22,7 @@ export interface AvatarProps {
   /** Srcset of image avatar */
   srcSet?: string;
   draggable?: boolean;
-  /** icon to be used in avatar */
+  /** Icon to be used in avatar */
   icon?: React.ReactNode;
   style?: React.CSSProperties;
   prefixCls?: string;

components/badge/index.tsx

@@ -22,7 +22,7 @@ export interface BadgeProps {
   showZero?: boolean;
   /** Max count to show */
   overflowCount?: number;
-  /** whether to show red dot without number */
+  /** Whether to show red dot without number */
   dot?: boolean;
   style?: React.CSSProperties;
   prefixCls?: string;

components/breadcrumb/BreadcrumbItem.tsx

@@ -26,10 +26,7 @@ const BreadcrumbItem: BreadcrumbItemInterface = ({
 }) => {
   const { getPrefixCls } = React.useContext(ConfigContext);
   const prefixCls = getPrefixCls('breadcrumb', customizePrefixCls);
-  /**
+  /** If overlay is have Wrap a DropDown */
-   * if overlay is have
-   * Wrap a DropDown
-   */
   const renderBreadcrumbNode = (breadcrumbItem: React.ReactNode) => {
     if (overlay) {
       return (

components/button/button.tsx

@@ -140,7 +140,7 @@ const InternalButton: React.ForwardRefRenderFunction<unknown, ButtonProps> = (pr
     icon,
     ghost = false,
     block = false,
-    /** if we extract items here, we dont need use omit.js */
+    /** If we extract items here, we don't need use omit.js */
     // React does not recognize the `htmlType` prop on a DOM element. Here we pick it out of `rest`.
     htmlType = 'button' as ButtonProps['htmlType'],
     ...rest

components/cascader/index.tsx

@@ -93,7 +93,7 @@ export interface CascaderProps {
   name?: string;
   /** 输入框id */
   id?: string;
-  /** whether has border style */
+  /** Whether has border style */
   bordered?: boolean;
   /** 禁用 */
   disabled?: boolean;
@@ -115,7 +115,7 @@ export interface CascaderProps {
   inputPrefixCls?: string;
   getPopupContainer?: (triggerNode: HTMLElement) => HTMLElement;
   popupVisible?: boolean;
-  /** use this after antd@3.7.0 */
+  /** Use this after antd@3.7.0 */
   fieldNames?: FieldNamesType;
   suffixIcon?: React.ReactNode;
   dropdownRender?: (menus: React.ReactNode) => React.ReactNode;

components/comment/index.tsx

@@ -9,7 +9,7 @@ export interface CommentProps {
   author?: React.ReactNode;
   /** The element to display as the comment avatar - generally an antd Avatar */
   avatar?: React.ReactNode;
-  /** className of comment */
+  /** ClassName of comment */
   className?: string;
   /** The main content of the comment */
   content: React.ReactNode;

components/date-picker/locale/ru_RU.tsx

@@ -1,6 +1,4 @@
-/**
+/** Created by Andrey Gayvoronsky on 13/04/16. */
- * Created by Andrey Gayvoronsky on 13/04/16.
- */
 
 import CalendarLocale from 'rc-picker/lib/locale/ru_RU';
 import TimePickerLocale from '../../time-picker/locale/ru_RU';

components/drawer/index.tsx

@@ -31,7 +31,7 @@ export interface DrawerProps {
   mask?: boolean;
   maskStyle?: React.CSSProperties;
   style?: React.CSSProperties;
-  /** wrapper dom node style of header and body */
+  /** Wrapper dom node style of header and body */
   drawerStyle?: React.CSSProperties;
   headerStyle?: React.CSSProperties;
   bodyStyle?: React.CSSProperties;

components/empty/index.tsx

@@ -16,9 +16,7 @@ export interface EmptyProps {
   prefixCls?: string;
   className?: string;
   style?: React.CSSProperties;
-  /**
+  /** @since 3.16.0 */
-   * @since 3.16.0
-   */
   imageStyle?: React.CSSProperties;
   image?: React.ReactNode;
   description?: React.ReactNode;

components/form/ErrorList.tsx

@@ -30,6 +30,7 @@ export default function ErrorList({
       if (changedVisible) {
         /**
          * We trigger in sync to avoid dom shaking but this get warning in react 16.13.
+         *
          * So use Promise to keep in micro async to handle this.
          * https://github.com/ant-design/ant-design/issues/21698#issuecomment-593743485
          */

components/form/FormItemInput.tsx

@@ -17,9 +17,7 @@ interface FormItemInputMiscProps {
   hasFeedback?: boolean;
   validateStatus?: ValidateStatus;
   onDomErrorVisibleChange: (visible: boolean) => void;
-  /**
+  /** @private Internal usage, do not use in any of your production. */
-   * @private Internal usage, do not use in any of your production.
-   */
   _internalItemRender?: {
     mark: string;
     render: (

components/form/context.tsx

@@ -7,10 +7,7 @@ import { FormLabelAlign } from './interface';
 import { RequiredMark } from './Form';
 import { ValidateStatus } from './FormItem';
 
-/**
+/** Form Context. Set top form style and pass to Form Item usage. */
- * Form Context
- * Set top form style and pass to Form Item usage.
- */
 export interface FormContextProps {
   vertical: boolean;
   name?: string;
@@ -28,10 +25,7 @@ export const FormContext = React.createContext<FormContextProps>({
   itemRef: (() => {}) as any,
 });
 
-/**
+/** Form Item Context. Used for Form noStyle Item error collection */
- * Form Item Context
- * Used for Form noStyle Item error collection
- */
 export interface FormItemContextProps {
   updateItemErrors: (name: string, errors: string[]) => void;
 }
@@ -40,10 +34,7 @@ export const FormItemContext = React.createContext<FormItemContextProps>({
   updateItemErrors: () => {},
 });
 
-/**
+/** Form Provider */
- * Form Provider
- *
- */
 export interface FormProviderProps extends Omit<RcFormProviderProps, 'validateMessages'> {}
 
 export const FormProvider: React.FC<FormProviderProps> = props => {
@@ -51,9 +42,7 @@ export const FormProvider: React.FC<FormProviderProps> = props => {
   return <RcFormProvider {...providerProps} />;
 };
 
-/**
+/** Used for ErrorList only */
- * Used for ErrorList only
- */
 export interface FormItemPrefixContextProps {
   prefixCls: string;
   status?: ValidateStatus;

components/form/hooks/useCacheErrors.ts

@@ -1,9 +1,7 @@
 import * as React from 'react';
 import useForceUpdate from '../../_util/hooks/useForceUpdate';
 
-/**
+/** Always debounce error to avoid [error -> null -> error] blink */
- * Always debounce error to avoid [error -> null -> error] blink
- */
 export default function useCacheErrors(
   errors: React.ReactNode[],
   changeTrigger: (visible: boolean) => void,

components/form/index.zh-CN.md

@@ -176,11 +176,13 @@ Form 通过增量更新方式，只更新被修改的字段相关组件以达到
 
 ```tsx
 <Form.List>
-  {fields => fields.map(field => (
+  {fields =>
+    fields.map(field => (
       <Form.Item {...field}>
         <Input />
       </Form.Item>
-  ))}
+    ))
+  }
 </Form.List>
 ```
 

components/input/ClearableLabeledInput.tsx

@@ -17,9 +17,7 @@ function hasAddon(props: InputProps | ClearableInputProps) {
   return !!(props.addonBefore || props.addonAfter);
 }
 
-/**
+/** This basic props required for input and textarea. */
- * This basic props required for input and textarea.
- */
 interface BasicProps {
   prefixCls: string;
   inputType: typeof ClearableInputType[number];
@@ -36,9 +34,7 @@ interface BasicProps {
   bordered: boolean;
 }
 
-/**
+/** This props only for input. */
- * This props only for input.
- */
 interface ClearableInputProps extends BasicProps {
   size?: SizeType;
   suffix?: React.ReactNode;

components/input/__tests__/textarea.test.js

@@ -58,12 +58,12 @@ describe('TextArea', () => {
     const wrapper = mount(
       <TextArea onKeyDown={fakeHandleKeyDown} onPressEnter={fakeHandlePressEnter} />,
     );
-    /** keyCode 65 is A */
+    /** KeyCode 65 is A */
     wrapper.find('textarea').simulate('keydown', { keyCode: 65 });
     expect(fakeHandleKeyDown).toHaveBeenCalledTimes(1);
     expect(fakeHandlePressEnter).toHaveBeenCalledTimes(0);
 
-    /** keyCode 13 is Enter */
+    /** KeyCode 13 is Enter */
     wrapper.find('textarea').simulate('keydown', { keyCode: 13 });
     expect(fakeHandleKeyDown).toHaveBeenCalledTimes(2);
     expect(fakeHandlePressEnter).toHaveBeenCalledTimes(1);

components/modal/confirm.tsx

@@ -60,6 +60,7 @@ export default function confirm(config: ModalFuncProps) {
   function render({ okText, cancelText, prefixCls, ...props }: any) {
     /**
      * https://github.com/ant-design/ant-design/issues/23623
+     *
      * Sync render blocks React event. Let's make this async.
      */
     setTimeout(() => {

components/progress/Line.tsx

@@ -11,12 +11,13 @@ interface LineProps extends ProgressProps {
 }
 
 /**
+ * @example
  *   {
- *   '0%': '#afc163',
+ *     "0%": "#afc163",
- *   '75%': '#009900',
+ *     "75%": "#009900",
- *   '50%': 'green',     ====>     '#afc163 0%, #66FF00 25%, #00CC00 50%, #009900 75%, #ffffff 100%'
+ *     "50%": "green", // ====> '#afc163 0%, #66FF00 25%, #00CC00 50%, #009900 75%, #ffffff 100%'
- *   '25%': '#66FF00',
+ *     "25%": "#66FF00",
- *   '100%': '#ffffff'
+ *     "100%": "#ffffff"
  *   }
  */
 export const sortGradient = (gradients: StringGradients) => {
@@ -35,19 +36,17 @@ export const sortGradient = (gradients: StringGradients) => {
 };
 
 /**
- * {
+ * Then this man came to realize the truth: Besides six pence, there is the moon. Besides bread and
- *   '0%': '#afc163',
+ * butter, there is the bug. And... Besides women, there is the code.
- *   '25%': '#66FF00',
- *   '50%': '#00CC00',     ====>  linear-gradient(to right, #afc163 0%, #66FF00 25%,
- *   '75%': '#009900',              #00CC00 50%, #009900 75%, #ffffff 100%)
- *   '100%': '#ffffff'
- * }
  *
- * Then this man came to realize the truth:
+ * @example
- * Besides six pence, there is the moon.
+ *   {
- * Besides bread and butter, there is the bug.
+ *     "0%": "#afc163",
- * And...
+ *     "25%": "#66FF00",
- * Besides women, there is the code.
+ *     "50%": "#00CC00", // ====>  linear-gradient(to right, #afc163 0%, #66FF00 25%,
+ *     "75%": "#009900", //        #00CC00 50%, #009900 75%, #ffffff 100%)
+ *     "100%": "#ffffff"
+ *   }
  */
 export const handleGradient = (strokeColor: ProgressGradient, directionConfig: DirectionType) => {
   const {

components/result/index.tsx

@@ -43,9 +43,8 @@ export interface ResultProps {
 const ExceptionStatus = Object.keys(ExceptionMap);
 
 /**
- * render icon
+ * Render icon if ExceptionStatus includes ,render svg image else render iconNode
- * if ExceptionStatus includes ,render svg image
+ *
- * else render iconNode
  * @param prefixCls
  * @param {status, icon}
  */

components/table/Column.tsx

@@ -5,10 +5,7 @@ export interface ColumnProps<RecordType> extends ColumnType<RecordType> {
 }
 
 /* istanbul ignore next */
-/**
+/** This is a syntactic sugar for `columns` prop. So HOC will not work on this. */
- * This is a syntactic sugar for `columns` prop.
- * So HOC will not work on this.
- */
 // eslint-disable-next-line no-unused-vars
 function Column<RecordType>(_: ColumnProps<RecordType>) {
   return null;

components/table/ColumnGroup.tsx

@@ -9,10 +9,7 @@ export interface ColumnGroupProps<RecordType> extends Omit<ColumnType<RecordType
 }
 
 /* istanbul ignore next */
-/**
+/** This is a syntactic sugar for `columns` prop. So HOC will not work on this. */
- * This is a syntactic sugar for `columns` prop.
- * So HOC will not work on this.
- */
 // eslint-disable-next-line no-unused-vars
 function ColumnGroup<RecordType>(_: ColumnGroupProps<RecordType>) {
   return null;

components/table/Table.tsx

@@ -233,10 +233,9 @@ function Table<RecordType extends object = any>(props: TableProps<RecordType>) {
   };
 
   /**
-   * Controlled state in `columns` is not a good idea that makes too many code (1000+ line?)
+   * Controlled state in `columns` is not a good idea that makes too many code (1000+ line?) to read
-   * to read state out and then put it back to title render.
+   * state out and then put it back to title render. Move these code into `hooks` but still too
-   * Move these code into `hooks` but still too complex.
+   * complex. We should provides Table props like `sorter` & `filter` to handle control in next big version.
-   * We should provides Table props like `sorter` & `filter` to handle control in next big version.
    */
 
   // ============================ Sorter =============================

components/table/__tests__/Table.pagination.test.js

@@ -239,9 +239,8 @@ describe('Table.pagination', () => {
   });
 
   /**
-   * `pagination` is not designed to accept `true` value,
+   * `pagination` is not designed to accept `true` value, but in practice, many people assign `true`
-   * but in practice, many people assign `true` to `pagination`,
+   * to `pagination`, since they misunderstand that `pagination` can accept a boolean value.
-   * since they misunderstand that `pagination` can accept a boolean value.
    */
   it('Accepts pagination as true', () => {
     const wrapper = mount(createTable({ pagination: true }));

components/tag/CheckableTag.tsx

@@ -7,8 +7,9 @@ export interface CheckableTagProps {
   className?: string;
   style?: React.CSSProperties;
   /**
-   * @description       it is an absolute controlled component and has no uncontrolled mode.
+   * It is an absolute controlled component and has no uncontrolled mode.
-   * @description.zh-CN 该组件为完全受控组件，不支持非受控用法。
+   *
+   * .zh-cn 该组件为完全受控组件，不支持非受控用法。
    */
   checked: boolean;
   onChange?: (checked: boolean) => void;

components/time-picker/locale/ru_RU.tsx

@@ -1,6 +1,4 @@
-/**
+/** Created by Andrey Gayvoronsky on 13/04/16. */
- * Created by Andrey Gayvoronsky on 13/04/16.
- */
 import { TimePickerLocale } from '../index';
 
 const locale: TimePickerLocale = {

components/timeline/TimelineItem.tsx

@@ -25,7 +25,7 @@ const TimelineItem: React.FC<TimelineItemProps> = ({
   color = 'blue',
   dot,
   pending = false,
-  position /** dead, but do not pass in <li {...omit()} */,
+  position /** Dead, but do not pass in <li {...omit()} */,
   label,
   children,
   ...restProps

components/transfer/list.tsx

@@ -52,7 +52,7 @@ export interface TransferListProps<RecordType> extends TransferLocale {
   onItemSelectAll: (dataSource: string[], checkAll: boolean) => void;
   onItemRemove?: (keys: string[]) => void;
   handleClear: () => void;
-  /** render item */
+  /** Render item */
   render?: (item: RecordType) => RenderResult;
   showSearch?: boolean;
   searchPlaceholder: string;

components/tree/Tree.tsx

@@ -99,7 +99,7 @@ export interface TreeProps extends Omit<RcTreeProps, 'prefixCls' | 'showLine' |
   multiple?: boolean;
   /** 是否自动展开父节点 */
   autoExpandParent?: boolean;
-  /** checkable状态下节点选择完全受控（父子节点选中状态不再关联） */
+  /** Checkable状态下节点选择完全受控（父子节点选中状态不再关联） */
   checkStrictly?: boolean;
   /** 是否支持选中 */
   checkable?: boolean;

package.json

@@ -234,6 +234,7 @@
     "node-fetch": "^2.6.0",
     "open": "^7.0.3",
     "prettier": "^2.2.0",
+    "prettier-plugin-jsdoc": "^0.2.12",
     "pretty-quick": "^3.0.0",
     "querystring": "^0.2.0",
     "rc-footer": "^0.6.3",

scripts/dark-vars.js

@@ -1,6 +1,7 @@
 /**
- * convert dark.less into js vars
+ * Convert dark.less into js vars
  *
+ * @example
  *   const darkVars = require('./dark-vars');
  */
 const fs = require('fs');

scripts/default-vars.js

@@ -1,6 +1,7 @@
 /**
- * convert default.less into js vars
+ * Convert default.less into js vars
  *
+ * @example
  *   const darkVars = require('./default-vars');
  */
 const fs = require('fs');

scripts/generateLegacyLocale.js

@@ -1,7 +1,5 @@
 /* eslint-disable no-console */
-/**
+/** Generate legacy locale file as shadow of `/locale` to `/locale-provider`. */
- * Generate legacy locale file as shadow of `/locale` to `/locale-provider`.
- */
 
 const glob = require('glob');
 const fs = require('fs');

site/theme/template/AppShell.jsx

@@ -1,5 +1,6 @@
 /**
  * Empty component for app shell
+ *
  * See https://github.com/NekR/offline-plugin/blob/master/docs/app-shell.md
  */
 import React from 'react';

tests/shared/demoTest.ts

@@ -10,7 +10,7 @@ const USE_REPLACEMENT = false;
 const testDist = process.env.LIB_DIR === 'dist';
 
 /**
- * rc component will generate id for aria usage.
+ * Rc component will generate id for aria usage.
  *     It's created as `test-uuid` when env === 'test'.
  *     Or `f7fa7a3c-a675-47bc-912e-0c45fb6a74d9`(randomly) when not test env.
  *     So we need hack of this to modify the `aria-controls`.