docs: improve the docs

Author: mdjastrzebski

src/user-event/setup/setup.ts

@@ -45,14 +45,20 @@ const defaultOptions: Required<UserEventSetupOptions> = {
  * Creates a new instance of user event instance with the given options.
  *
  * @param options
- * @returns
+ * @returns UserEvent instance
  */
 export function setup(options?: UserEventSetupOptions) {
   const config = createConfig(options);
   const instance = createInstance(config);
   return instance;
 }
 
+/**
+ * Options affecting all user event interactions.
+ *
+ * @param delay between some subsequent inputs like typing a series of characters
+ * @param advanceTimers function to be called to advance fake timers
+ */
 export interface UserEventConfig {
   delay: number;
   advanceTimers: (delay: number) => Promise<void> | void;
@@ -65,9 +71,34 @@ function createConfig(options?: UserEventSetupOptions): UserEventConfig {
   };
 }
 
+/**
+ * UserEvent instance used to invoke user interaction functions.
+ */
 export interface UserEventInstance {
   config: UserEventConfig;
+
   press: (element: ReactTestInstance) => Promise<void>;
+
+  /**
+   * Simulate user pressing on given `TextInput` element and typing given text.
+   *
+   * This method will trigger the events for each character of the text:
+   * `keyPress`, `change`, `changeText`, `endEditing`, etc.
+   *
+   * It will also trigger events connected with entering and leaving the text
+   * input.
+   *
+   * The exact events sent depend on the props of TextInput (`editable`,
+   * `multiline`, value, defaultValue, etc) and passed options.
+   *
+   * @param element TextInput element to type on
+   * @param text Text to type
+   * @param options Options affecting typing behavior:
+   *  - `skipPress` - if true, `pressIn` and `pressOut` events will not be
+   *   triggered.
+   * - `submitEditing` - if true, `submitEditing` event will be triggered after
+   * typing the text.
+   */
   type: (
     element: ReactTestInstance,
     text: string,

src/user-event/type/__tests__/type.test.tsx

@@ -3,6 +3,7 @@ import { View, TextInput, TextInputProps } from 'react-native';
 import { createEventLogger } from '../../../test-utils/events';
 import { render } from '../../..';
 import { userEvent } from '../..';
+import { UserEventInstance } from '../../setup';
 
 beforeEach(() => {
   jest.useRealTimers();

website/docs/UserEvent.md

@@ -8,6 +8,7 @@ title: User Event
 - [`userEvent.setup`](#usereventsetup)
   - [Options](#options)
 - [`type()`](#type)
+  - [Options:](#options-1)
   - [Sequence of events](#sequence-of-events)
 
 
@@ -44,10 +45,25 @@ type(
 ): Promise<void>
 ```
 
+Example
+```ts
+await user.type(textInput, "Hello world!");
+```
+
 This helper simulates user focusing on `TextInput` element, typing `text` one character at a time, and leaving the element.
 
+This function supports only host `TextInput` elements. Passing other element type will result in throwing error.
+
+### Options:
+ - `skipPress` - if true, `pressIn` and `pressOut` events will not be triggered.
+ - `submitEditing` - if true, `submitEditing` event will be triggered after typing the text.
+
 ### Sequence of events
 
+The sequence of events depends on `multiline` prop, as well as passed options.
+
+Events will not be emitted if `editable` prop is set to `false`.
+
 Entering the element:
 - `pressIn` (optional)
 - `focus`