Add docs about v1 onSubmit behavior

docs/api/formik.md

@@ -325,7 +325,7 @@ Note: `initialValues` not available to the higher-order component, use
 Your optional form reset handler. It is passed your forms `values` and the
 "FormikBag".
 
-### `onSubmit: (values: Values, formikBag: FormikBag) => void`
+### `onSubmit: (values: Values, formikBag: FormikBag) => void | Promise<void>`
 
 Your form submission handler. It is passed your forms `values` and the
 "FormikBag", which includes an object containing a subset of the
@@ -336,6 +336,8 @@ passed to the wrapped component.
 Note: `errors`, `touched`, `status` and all event handlers are NOT
 included in the `FormikBag`.
 
+> IMPORTANT: If `onSubmit` is async, then Formik will automatically set `isSubmitting` to `false` on your behalf once it has resolved. This means you do NOT need to call `formikBag.setSubmitting(false)` manually. However, if your `onSubmit` function is synchronous, then you need to call `setSubmitting(false)` on your own.
+
 ### `validate?: (values: Values) => FormikErrors<Values> | Promise<any>`
 
 _Note: I suggest using `validationSchema` and Yup for validation. However,

docs/api/withFormik.md

@@ -87,7 +87,7 @@ class components (e.g. `class XXXXX extends React.Component {..}`).
 Default is `false`. Control whether Formik should reset the form if the wrapped
 component props change (using deep equality).
 
-### `handleSubmit: (values: Values, formikBag: FormikBag) => void`
+### `handleSubmit: (values: Values, formikBag: FormikBag) => void | Promise<void>`
 
 Your form submission handler. It is passed your forms `values` and the
 "FormikBag", which includes an object containing a subset of the
@@ -111,6 +111,8 @@ passed to the wrapped component.
 Note: `errors`, `touched`, `status` and all event handlers are NOT
 included in the `FormikBag`.
 
+> IMPORTANT: If `onSubmit` is async, then Formik will automatically set `isSubmitting` to `false` on your behalf once it has resolved. This means you do NOT need to call `formikBag.setSubmitting(false)` manually. However, if your `onSubmit` function is synchronous, then you need to call `setSubmitting(false)` on your own.
+
 ### `isInitialValid?: boolean | (props: Props) => boolean`
 
 **Deprecated in 2.x, use `mapPropsToErrors` instead**