From 22c60f5926c975488d47597fbfe7a411322e8804 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 14:29:48 +0100
Subject: [PATCH 01/24] Use a central script instead of one per package

---
 bin/generate-docs.sh | 3 +++
 1 file changed, 3 insertions(+)
 create mode 100755 bin/generate-docs.sh

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
new file mode 100755
index 0000000000000..c7ec1314d9b51
--- /dev/null
+++ b/bin/generate-docs.sh
@@ -0,0 +1,3 @@
+#!/bin/bash
+
+npx docgen packages/e2e-test-utils/src/index.js --output packages/e2e-test-utils/README.md --to-token

From e7ba66233aa25e0586436eb535b27ecd88d8b54e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 14:53:11 +0100
Subject: [PATCH 02/24] Prepare to add more packages

---
 bin/generate-docs.sh | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
index c7ec1314d9b51..afdebea2977d4 100755
--- a/bin/generate-docs.sh
+++ b/bin/generate-docs.sh
@@ -1,3 +1,10 @@
 #!/bin/bash
 
-npx docgen packages/e2e-test-utils/src/index.js --output packages/e2e-test-utils/README.md --to-token
+declare -a packages=(
+	"e2e-test-utils"
+)
+
+for package in "${packages[@]}"
+do
+	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token;
+done

From 988deb2d8eb2d5fd841f0c545593c72aabfb741b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 19:06:08 +0100
Subject: [PATCH 03/24] Merge docs:build and docs:generate

---
 bin/generate-docs.sh | 10 ----------
 1 file changed, 10 deletions(-)
 delete mode 100755 bin/generate-docs.sh

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
deleted file mode 100755
index afdebea2977d4..0000000000000
--- a/bin/generate-docs.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#!/bin/bash
-
-declare -a packages=(
-	"e2e-test-utils"
-)
-
-for package in "${packages[@]}"
-do
-	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token;
-done

From 692faa77e49a33c0afe984e9d829a4bac6525e99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 1 Mar 2019 20:35:03 +0100
Subject: [PATCH 04/24] Autogenerated docs and setup for rich-text

---
 packages/rich-text/README.md    | 549 ++++++++++++++++++++++++++------
 packages/rich-text/package.json |   6 +
 2 files changed, 451 insertions(+), 104 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index be3d703b2678f..41be6dc6aa691 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -14,169 +14,510 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ## Usage
 
-### create
+<!-- START TOKEN(Autogenerated API docs) -->
 
-```js
-create( {
-	?element: Element,
-	?text: string,
-	?html: string,
-	?range: Range,
-	?multilineTag: string,
-	?multilineWrapperTags: Array,
-} ): Object
-```
+### apply
 
-Create a RichText value from an `Element` tree (DOM), an HTML string or a plain text string, with optionally a `Range` object to set the selection. If called without any arguments, an empty value will be created. If `multilineTag` is provided, any content of direct children whose type matches `multilineTag` will be separated by a line separator.
+[src/index.js#L27-L27](src/index.js#L27-L27)
 
-### toHTMLString
+Create an `Element` tree from a Rich Text value and applies the difference to
+the `Element` tree contained by `current`. If a `multilineTag` is provided,
+text separated by two new lines will be wrapped in an `Element` of that type.
 
-```js
-toHTMLString( {
-	value: Object,
-	?multilineTag: string,
-	?multilineWrapperTags: Array,
-} ): string
-```
+**Parameters**
 
-Create an HTML string from a Rich Text value. If a `multilineTag` is provided, text separated by a line separator will be wrapped in it.
+-   **value** `Object`: Value to apply.
+-   **current** `HTMLElement`: The live root node to apply the element tree to.
+-   **multilineTag** `string`: Multiline tag.
 
-### apply
+### applyFormat
 
-```js
-apply( {
-	value: Object,
-	current: Element,
-	?multilineTag: string
-	?multilineWrapperTags: Array,
-} ): void
-```
+[src/index.js#L6-L6](src/index.js#L6-L6)
 
-Create an `Element` tree from a Rich Text value and applies the difference to the `Element` tree contained by `current`. If a `multilineTag` is provided, text separated by two new lines will be wrapped in an `Element` of that type.
+Apply a format object to a Rich Text value from the given `startIndex` to the
+given `endIndex`. Indices are retrieved from the selection if none are
+provided.
 
-### isCollapsed
+**Parameters**
 
-```js
-isCollapsed( value: Object ): ?boolean
-```
+-   **value** `Object`: Value to modify.
+-   **format** `Object`: Format to apply.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
 
-Check if the selection of a Rich Text value is collapsed or not. Collapsed means that no characters are selected, but there is a caret present. If there is no selection, `undefined` will be returned. This is similar to `window.getSelection().isCollapsed()`.
+**Returns**
 
-### isEmpty
+`Object` A new value with the format applied.
 
-```js
-isEmpty( value: Object ): boolean
-```
+### changeListType
 
-Check if a Rich Text value is Empty, meaning it contains no text or any objects (such as images).
+[src/index.js#L34-L34](src/index.js#L34-L34)
 
-### applyFormat
+Changes the list type of the selected indented list, if any. Looks at the
+currently selected list item and takes the parent list, then changes the list
+type of this list. When multiple lines are selected, the parent lists are
+takes and changed.
 
-```js
-applyFormat( value: Object, format: Object, ?startIndex: number, ?endIndex: number ): Object
-```
+**Parameters**
 
-Apply a format object to a Rich Text value from the given `startIndex` to the given `endIndex`. Indices are retrieved from the selection if none are provided.
+-   **value** `Object`: Value to change.
+-   **newFormat** `Object`: The new list format object. Choose between `{ type: 'ol' }` and `{ type: 'ul' }`.
 
-### removeFormat
+**Returns**
 
-```js
-removeFormat( value: Object, formatType: string, ?startIndex: number, ?endIndex: number ): Object
-```
+`Object` The changed value.
 
-Remove any format object from a Rich Text value by type from the given `startIndex` to the given `endIndex`. Indices are retrieved from the selection if none are provided.
+### charAt
 
-### toggleFormat
+[src/index.js#L7-L7](src/index.js#L7-L7)
 
-```js
-toggleFormat( value: Object, format: Object ): Object
-```
+Gets the character at the specified index, or returns `undefined` if no
+character was found.
+
+**Parameters**
+
+-   **value** `Object`: Value to get the character from.
+-   **index** `string`: Index to use.
+
+**Returns**
+
+`?string` A one character long string, or undefined.
+
+### concat
+
+[src/index.js#L8-L8](src/index.js#L8-L8)
 
-Toggles a format object to a Rich Text value at the current selection, and returns a new value with the format applied or removed.
+Combine all Rich Text values into one. This is similar to
+`String.prototype.concat`.
+
+**Parameters**
+
+-   **values** `...Object`: Objects to combine.
+
+**Returns**
+
+`Object` A new value combining all given records.
+
+### create
+
+[src/index.js#L9-L9](src/index.js#L9-L9)
+
+Create a RichText value from an `Element` tree (DOM), an HTML string or a
+plain text string, with optionally a `Range` object to set the selection. If
+called without any input, an empty value will be created. If
+`multilineTag` is provided, any content of direct children whose type matches
+`multilineTag` will be separated by two newlines. The optional functions can
+be used to filter out content.
+
+**Parameters**
+
+-   **$1** `?Object`: Optional named argements.
+-   **$1.element** `?Element`: Element to create value from.
+-   **$1.text** `?string`: Text to create value from.
+-   **$1.html** `?string`: HTML to create value from.
+-   **$1.range** `?Range`: Range to create value from.
+-   **$1.multilineTag** `?string`: Multiline tag if the structure is multiline.
+-   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
+
+**Returns**
+
+`Object` A rich text value.
 
 ### getActiveFormat
 
-```js
-getActiveFormat( value: Object, formatType: string ): ?Object
-```
+[src/index.js#L10-L10](src/index.js#L10-L10)
+
+Gets the format object by type at the start of the selection. This can be
+used to get e.g. the URL of a link format at the current selection, but also
+to check if a format is active at the selection. Returns undefined if there
+is no format at the selection.
+
+**Parameters**
+
+-   **value** `Object`: Value to inspect.
+-   **formatType** `string`: Format type to look for.
+
+**Returns**
+
+`?Object` Active format object of the specified type, or undefined.
+
+### getSelectionEnd
+
+[src/index.js#L11-L11](src/index.js#L11-L11)
+
+Gets the end index of the current selection, or returns `undefined` if no
+selection exists. The selection ends right before the character at this
+index.
+
+**Parameters**
+
+-   **value** `Object`: Value to get the selection from.
+
+**Returns**
+
+`?number` Index where the selection ends.
 
-Get any format object by type at the start of the selection. This can be used to get e.g. the URL of a link format at the current selection, but also to check if a format is active at the selection. Returns undefined if there is no format at the selection.
+### getSelectionStart
+
+[src/index.js#L12-L12](src/index.js#L12-L12)
+
+Gets the start index of the current selection, or returns `undefined` if no
+selection exists. The selection starts right before the character at this
+index.
+
+**Parameters**
+
+-   **value** `Object`: Value to get the selection from.
+
+**Returns**
+
+`?number` Index where the selection starts.
 
 ### getTextContent
 
-```js
-getTextContent( value: Object ): string
-```
+[src/index.js#L13-L13](src/index.js#L13-L13)
 
-Get the textual content of a Rich Text value. This is similar to `Element.textContent`.
+Get the textual content of a Rich Text value. This is similar to
+`Element.textContent`.
 
-### slice
+**Parameters**
 
-```js
-slice( value: Object, ?startIndex: number, ?endIndex: number ): Object
-```
+-   **value** `Object`: Value to use.
 
-Slice a Rich Text value from `startIndex` to `endIndex`. Indices are retrieved from the selection if none are provided. This is similar to `String.prototype.slice`.
+**Returns**
 
-### replace
+`string` The text content.
 
-```js
-replace( value: Object, pattern: RegExp, replacement: Object | string ): Object
-```
+### indentListItems
+
+[src/index.js#L32-L32](src/index.js#L32-L32)
+
+Indents any selected list items if possible.
 
-Search a Rich Text value and replace the match(es) with `replacement`. This is similar to `String.prototype.replace`.
+**Parameters**
+
+-   **value** `Object`: Value to change.
+-   **rootFormat** `Object`: 
+
+**Returns**
+
+`Object` The changed value.
 
 ### insert
 
-```js
-insert( value: Object, valueToInsert: Object | string, ?startIndex: number, ?endIndex: number ): Object
-```
+[src/index.js#L21-L21](src/index.js#L21-L21)
+
+Insert a Rich Text value, an HTML string, or a plain text string, into a
+Rich Text value at the given `startIndex`. Any content between `startIndex`
+and `endIndex` will be removed. Indices are retrieved from the selection if
+none are provided.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+-   **valueToInsert** `string`: Value to insert.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
+
+**Returns**
+
+`Object` A new value with the value inserted.
+
+### insertLineBreak
+
+[src/index.js#L22-L22](src/index.js#L22-L22)
+
+Inserts a line break at the given or selected position. Inserts two line
+breaks if at the end of a line.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+
+**Returns**
+
+`Object` The value with the line break(s) inserted.
+
+### insertLineSeparator
+
+[src/index.js#L23-L23](src/index.js#L23-L23)
+
+Insert a line break character into a Rich Text value at the given
+`startIndex`. Any content between `startIndex` and `endIndex` will be
+removed. Indices are retrieved from the selection if none are provided.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
+
+**Returns**
+
+`Object` A new value with the value inserted.
+
+### insertObject
+
+[src/index.js#L24-L24](src/index.js#L24-L24)
+
+Insert a format as an object into a Rich Text value at the given
+`startIndex`. Any content between `startIndex` and `endIndex` will be
+removed. Indices are retrieved from the selection if none are provided.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+-   **formatToInsert** `Object`: Format to insert as object.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
+
+**Returns**
+
+`Object` A new value with the object inserted.
+
+### isCollapsed
+
+[src/index.js#L14-L14](src/index.js#L14-L14)
+
+Check if the selection of a Rich Text value is collapsed or not. Collapsed
+means that no characters are selected, but there is a caret present. If there
+is no selection, `undefined` will be returned. This is similar to
+`window.getSelection().isCollapsed()`.
+
+**Parameters**
+
+-   **value** `Object`: The rich text value to check.
 
-Insert a Rich Text value, an HTML string, or a plain text string, into a Rich Text value at the given `startIndex`. Any content between `startIndex` and `endIndex` will be removed. Indices are retrieved from the selection if none are provided.
+**Returns**
+
+`?boolean` True if the selection is collapsed, false if not, undefined if there is no selection.
+
+### isEmpty
+
+[src/index.js#L15-L15](src/index.js#L15-L15)
+
+Check if a Rich Text value is Empty, meaning it contains no text or any
+objects (such as images).
+
+**Parameters**
+
+-   **value** `Object`: Value to use.
+
+**Returns**
+
+`boolean` True if the value is empty, false if not.
+
+### isEmptyLine
+
+[src/index.js#L15-L15](src/index.js#L15-L15)
+
+Check if the current collapsed selection is on an empty line in case of a
+multiline value.
+
+**Parameters**
+
+-   **value** `Object`: Value te check.
+
+**Returns**
+
+`boolean` True if the line is empty, false if not.
+
+### join
+
+[src/index.js#L16-L16](src/index.js#L16-L16)
+
+Combine an array of Rich Text values into one, optionally separated by
+`separator`, which can be a Rich Text value, HTML string, or plain text
+string. This is similar to `Array.prototype.join`.
+
+**Parameters**
+
+-   **values** `Array`: An array of values to join.
+-   **separator** `(string|Object)`: Separator string or value.
+
+**Returns**
+
+`Object` A new combined value.
+
+### LINE_SEPARATOR
+
+[src/index.js#L30-L30](src/index.js#L30-L30)
+
+Undocumented declaration.
+
+### outdentListItems
+
+[src/index.js#L33-L33](src/index.js#L33-L33)
+
+Outdents any selected list items if possible.
+
+**Parameters**
+
+-   **value** `Object`: Value to change.
+
+**Returns**
+
+`Object` The changed value.
 
 ### registerFormatType
 
-```js
-registerFormatType( name: String, settings: Object ): ?WPformat
-```
+[src/index.js#L17-L17](src/index.js#L17-L17)
+
+Registers a new format provided a unique name and an object defining its
+behavior.
+
+**Parameters**
 
-Registers a new format provided a unique name and an object defining its behavior. Settings object:
+-   **name** `string`: Format name.
+-   **settings** `Object`: Format settings.
 
-- `tagName`: String. The HTML tag this format will wrap the selection with.
-- `className`: String || null. A class to match the format.
-- `title`: String. Name of the format.
-- `edit`: function. Should return a component for the user to interact with the new registered format.
+**Returns**
+
+`?WPFormat` The format, if it has been successfully registered; otherwise `undefined`.
 
 ### remove
 
-```js
-remove( value: Object, ?startIndex: number, ?endIndex: number ): Object
-```
+[src/index.js#L19-L19](src/index.js#L19-L19)
+
+Remove content from a Rich Text value between the given `startIndex` and
+`endIndex`. Indices are retrieved from the selection if none are provided.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
+
+**Returns**
+
+`Object` A new value with the content removed.
+
+### removeFormat
+
+[src/index.js#L18-L18](src/index.js#L18-L18)
+
+Remove any format object from a Rich Text value by type from the given
+`startIndex` to the given `endIndex`. Indices are retrieved from the
+selection if none are provided.
+
+**Parameters**
 
-Remove content from a Rich Text value between the given `startIndex` and `endIndex`. Indices are retrieved from the selection if none are provided.
+-   **value** `Object`: Value to modify.
+-   **formatType** `string`: Format type to remove.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
+
+**Returns**
+
+`Object` A new value with the format applied.
+
+### replace
+
+[src/index.js#L20-L20](src/index.js#L20-L20)
+
+Search a Rich Text value and replace the match(es) with `replacement`. This
+is similar to `String.prototype.replace`.
+
+**Parameters**
+
+-   **value** `Object`: The value to modify.
+-   **pattern** `(RegExp|string)`: A RegExp object or literal. Can also be a string. It is treated as a verbatim string and is not interpreted as a regular expression. Only the first occurrence will be replaced.
+-   **replacement** `(Function|string)`: The match or matches are replaced with the specified or the value returned by the specified function.
+
+**Returns**
+
+`Object` A new value with replacements applied.
+
+### slice
+
+[src/index.js#L25-L25](src/index.js#L25-L25)
+
+Slice a Rich Text value from `startIndex` to `endIndex`. Indices are
+retrieved from the selection if none are provided. This is similar to
+`String.prototype.slice`.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+-   **startIndex** `number`: Start index.
+-   **endIndex** `number`: End index.
+
+**Returns**
+
+`Object` A new extracted value.
 
 ### split
 
-```js
-split( value: Object, ?startIndex: number | string | RegExp, ?endIndex: number ): Array<Object>
-```
+[src/index.js#L26-L26](src/index.js#L26-L26)
 
-Split a Rich Text value in two at the given `startIndex` and `endIndex`, or split at the given separator. This is similar to `String.prototype.split`. Indices are retrieved from the selection if none are provided.
+Split a Rich Text value in two at the given `startIndex` and `endIndex`, or
+split at the given separator. This is similar to `String.prototype.split`.
+Indices are retrieved from the selection if none are provided.
 
-### join
+**Parameters**
 
-```js
-join( values: Array<Object>, ?separator: Object | string ): Object
-```
+-   **value** `Object`: Value to modify.
+-   **string** `(number|string)`: Start index, or string at which to split.
+-   **end** `number`: End index.
 
-Combine an array of Rich Text values into one, optionally separated by `separator`, which can be a Rich Text value, HTML string, or plain text string. This is similar to `Array.prototype.join`.
+**Returns**
 
-### concat
+`Array` An array of new values.
+
+### toggleFormat
+
+[src/index.js#L29-L29](src/index.js#L29-L29)
+
+Toggles a format object to a Rich Text value at the current selection.
+
+**Parameters**
+
+-   **value** `Object`: Value to modify.
+-   **format** `Object`: Format to apply or remove.
+
+**Returns**
+
+`Object` A new value with the format applied or removed.
+
+### toHTMLString
+
+[src/index.js#L28-L28](src/index.js#L28-L28)
+
+Create an HTML string from a Rich Text value. If a `multilineTag` is
+provided, text separated by a line separator will be wrapped in it.
+
+**Parameters**
+
+-   **$1** `Object`: Named argements.
+-   **$1.value** `Object`: Rich text value.
+-   **$1.multilineTag** `string`: Multiline tag.
+-   **$1.multilineWrapperTags** `Array`: Tags where lines can be found if nesting is possible.
+
+**Returns**
+
+`string` HTML string.
+
+### unregisterFormatType
+
+[src/index.js#L31-L31](src/index.js#L31-L31)
+
+Unregisters a format.
+
+**Parameters**
+
+-   **name** `string`: Format name.
+
+**Returns**
+
+`?WPFormat` The previous format value, if it has been successfully unregistered; otherwise `undefined`.
+
+### unstableToDom
+
+[src/index.js#L27-L27](src/index.js#L27-L27)
+
+Undocumented declaration.
 
-```js
-concat( ...values: Array<Object> ): Object
-```
 
-Combine all Rich Text values into one. This is similar to `String.prototype.concat`.
+<!-- END TOKEN(Autogenerated API docs) -->
 
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>
diff --git a/packages/rich-text/package.json b/packages/rich-text/package.json
index 824ce28ef1d18..690204c53f02c 100644
--- a/packages/rich-text/package.json
+++ b/packages/rich-text/package.json
@@ -28,7 +28,13 @@
 		"lodash": "^4.17.11",
 		"rememo": "^3.0.0"
 	},
+	"devDependencies": {
+		"@wordpress/docgen": "file:../docgen"
+	},
 	"publishConfig": {
 		"access": "public"
+	},
+	"scripts": {
+		"docs:generate": "docgen ./src/index.js --output ./README.md --to-token"
 	}
 }

From 70d49521c5ae38930f497e3a96ca851a1cab4b5a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 17:13:48 +0100
Subject: [PATCH 05/24] Use bin script instead of npm script

---
 bin/generate-docs.sh            | 11 +++++++++++
 packages/rich-text/package.json |  6 ------
 2 files changed, 11 insertions(+), 6 deletions(-)
 create mode 100755 bin/generate-docs.sh

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
new file mode 100755
index 0000000000000..6dd44ab3bcda5
--- /dev/null
+++ b/bin/generate-docs.sh
@@ -0,0 +1,11 @@
+#!/bin/bash
+
+declare -a packages=(
+	"e2e-test-utils"
+	"rich-text"
+)
+
+for package in "${packages[@]}"
+do
+	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token;
+done
diff --git a/packages/rich-text/package.json b/packages/rich-text/package.json
index 690204c53f02c..824ce28ef1d18 100644
--- a/packages/rich-text/package.json
+++ b/packages/rich-text/package.json
@@ -28,13 +28,7 @@
 		"lodash": "^4.17.11",
 		"rememo": "^3.0.0"
 	},
-	"devDependencies": {
-		"@wordpress/docgen": "file:../docgen"
-	},
 	"publishConfig": {
 		"access": "public"
-	},
-	"scripts": {
-		"docs:generate": "docgen ./src/index.js --output ./README.md --to-token"
 	}
 }

From a8fcc073385e4dfde778793702e5699ba1508fd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 17:14:51 +0100
Subject: [PATCH 06/24] Update JSDoc from old README and regenerate

---
 packages/rich-text/README.md             | 41 +++++++++++++-----------
 packages/rich-text/src/apply-format.js   |  4 +--
 packages/rich-text/src/insert.js         |  6 ++--
 packages/rich-text/src/join.js           |  2 +-
 packages/rich-text/src/remove-format.js  |  4 +--
 packages/rich-text/src/remove.js         |  4 +--
 packages/rich-text/src/slice.js          |  4 +--
 packages/rich-text/src/split.js          |  4 +--
 packages/rich-text/src/to-dom.js         | 10 +++---
 packages/rich-text/src/to-html-string.js |  4 +--
 10 files changed, 44 insertions(+), 39 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 41be6dc6aa691..74173d0f413ac 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -26,9 +26,12 @@ text separated by two new lines will be wrapped in an `Element` of that type.
 
 **Parameters**
 
--   **value** `Object`: Value to apply.
--   **current** `HTMLElement`: The live root node to apply the element tree to.
--   **multilineTag** `string`: Multiline tag.
+-   **$1** `Object`: Named arguments.
+-   **$1.value** `Object`: Value to apply.
+-   **$1.current** `HTMLElement`: The live root node to apply the element tree to.
+-   **$1.multilineTag** `?string`: Multiline tag.
+-   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
+-   **$1.prepareEditableTree** `?Array`: Functions to prepare the editable tree.
 
 ### applyFormat
 
@@ -42,8 +45,8 @@ provided.
 
 -   **value** `Object`: Value to modify.
 -   **format** `Object`: Format to apply.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **startIndex** `?number`: Start index.
+-   **endIndex** `?number`: End index.
 
 **Returns**
 
@@ -215,9 +218,9 @@ none are provided.
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **valueToInsert** `string`: Value to insert.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **valueToInsert** `(Object|string)`: Value to insert.
+-   **startIndex** `?number`: Start index.
+-   **endIndex** `?number`: End index.
 
 **Returns**
 
@@ -333,7 +336,7 @@ string. This is similar to `Array.prototype.join`.
 **Parameters**
 
 -   **values** `Array`: An array of values to join.
--   **separator** `(string|Object)`: Separator string or value.
+-   **separator** `?(string|Object)`: Separator string or value.
 
 **Returns**
 
@@ -385,8 +388,8 @@ Remove content from a Rich Text value between the given `startIndex` and
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **startIndex** `?number`: Start index.
+-   **endIndex** `?number`: End index.
 
 **Returns**
 
@@ -404,8 +407,8 @@ selection if none are provided.
 
 -   **value** `Object`: Value to modify.
 -   **formatType** `string`: Format type to remove.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **startIndex** `?number`: Start index.
+-   **endIndex** `?number`: End index.
 
 **Returns**
 
@@ -439,8 +442,8 @@ retrieved from the selection if none are provided. This is similar to
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **startIndex** `?number`: Start index.
+-   **endIndex** `?number`: End index.
 
 **Returns**
 
@@ -457,8 +460,8 @@ Indices are retrieved from the selection if none are provided.
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **string** `(number|string)`: Start index, or string at which to split.
--   **end** `number`: End index.
+-   **string** `?(number|string)`: Start index, or string at which to split.
+-   **endStr** `?number`: End index.
 
 **Returns**
 
@@ -490,8 +493,8 @@ provided, text separated by a line separator will be wrapped in it.
 
 -   **$1** `Object`: Named argements.
 -   **$1.value** `Object`: Rich text value.
--   **$1.multilineTag** `string`: Multiline tag.
--   **$1.multilineWrapperTags** `Array`: Tags where lines can be found if nesting is possible.
+-   **$1.multilineTag** `?string`: Multiline tag.
+-   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
 
 **Returns**
 
diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js
index 271be1176931d..15c6a5e1df022 100644
--- a/packages/rich-text/src/apply-format.js
+++ b/packages/rich-text/src/apply-format.js
@@ -17,8 +17,8 @@ import { normaliseFormats } from './normalise-formats';
  *
  * @param {Object} value      Value to modify.
  * @param {Object} format     Format to apply.
- * @param {number} startIndex Start index.
- * @param {number} endIndex   End index.
+ * @param {?number} startIndex Start index.
+ * @param {?number} endIndex   End index.
  *
  * @return {Object} A new value with the format applied.
  */
diff --git a/packages/rich-text/src/insert.js b/packages/rich-text/src/insert.js
index 10c2ec0e9621a..abfb1832f0d97 100644
--- a/packages/rich-text/src/insert.js
+++ b/packages/rich-text/src/insert.js
@@ -12,9 +12,9 @@ import { normaliseFormats } from './normalise-formats';
  * none are provided.
  *
  * @param {Object} value         Value to modify.
- * @param {string} valueToInsert Value to insert.
- * @param {number} startIndex    Start index.
- * @param {number} endIndex      End index.
+ * @param {Object|string} valueToInsert Value to insert.
+ * @param {?number} startIndex    Start index.
+ * @param {?number} endIndex      End index.
  *
  * @return {Object} A new value with the value inserted.
  */
diff --git a/packages/rich-text/src/join.js b/packages/rich-text/src/join.js
index c2e3c103b0674..0dba527e3456f 100644
--- a/packages/rich-text/src/join.js
+++ b/packages/rich-text/src/join.js
@@ -11,7 +11,7 @@ import { normaliseFormats } from './normalise-formats';
  * string. This is similar to `Array.prototype.join`.
  *
  * @param {Array}         values    An array of values to join.
- * @param {string|Object} separator Separator string or value.
+ * @param {?(string|Object)} separator Separator string or value.
  *
  * @return {Object} A new combined value.
  */
diff --git a/packages/rich-text/src/remove-format.js b/packages/rich-text/src/remove-format.js
index d6f2890f3afaf..89ccecbbb31b2 100644
--- a/packages/rich-text/src/remove-format.js
+++ b/packages/rich-text/src/remove-format.js
@@ -17,8 +17,8 @@ import { normaliseFormats } from './normalise-formats';
  *
  * @param {Object} value      Value to modify.
  * @param {string} formatType Format type to remove.
- * @param {number} startIndex Start index.
- * @param {number} endIndex   End index.
+ * @param {?number} startIndex Start index.
+ * @param {?number} endIndex   End index.
  *
  * @return {Object} A new value with the format applied.
  */
diff --git a/packages/rich-text/src/remove.js b/packages/rich-text/src/remove.js
index de4241ad301e6..8557605cc0597 100644
--- a/packages/rich-text/src/remove.js
+++ b/packages/rich-text/src/remove.js
@@ -10,8 +10,8 @@ import { create } from './create';
  * `endIndex`. Indices are retrieved from the selection if none are provided.
  *
  * @param {Object} value      Value to modify.
- * @param {number} startIndex Start index.
- * @param {number} endIndex   End index.
+ * @param {?number} startIndex Start index.
+ * @param {?number} endIndex   End index.
  *
  * @return {Object} A new value with the content removed.
  */
diff --git a/packages/rich-text/src/slice.js b/packages/rich-text/src/slice.js
index 3a54642b98cc7..768570d1680f0 100644
--- a/packages/rich-text/src/slice.js
+++ b/packages/rich-text/src/slice.js
@@ -4,8 +4,8 @@
  * `String.prototype.slice`.
  *
  * @param {Object} value       Value to modify.
- * @param {number} startIndex  Start index.
- * @param {number} endIndex    End index.
+ * @param {?number} startIndex  Start index.
+ * @param {?number} endIndex    End index.
  *
  * @return {Object} A new extracted value.
  */
diff --git a/packages/rich-text/src/split.js b/packages/rich-text/src/split.js
index d8b40b5aafb75..0fc28fdfae612 100644
--- a/packages/rich-text/src/split.js
+++ b/packages/rich-text/src/split.js
@@ -10,8 +10,8 @@ import { replace } from './replace';
  * Indices are retrieved from the selection if none are provided.
  *
  * @param {Object}        value   Value to modify.
- * @param {number|string} string  Start index, or string at which to split.
- * @param {number}        end     End index.
+ * @param {?(number|string)} string  Start index, or string at which to split.
+ * @param {?number}        endStr     End index.
  *
  * @return {Array} An array of new values.
  */
diff --git a/packages/rich-text/src/to-dom.js b/packages/rich-text/src/to-dom.js
index 987849172bf5f..524be4f4eb518 100644
--- a/packages/rich-text/src/to-dom.js
+++ b/packages/rich-text/src/to-dom.js
@@ -164,10 +164,12 @@ export function toDom( {
  * the `Element` tree contained by `current`. If a `multilineTag` is provided,
  * text separated by two new lines will be wrapped in an `Element` of that type.
  *
- * @param {Object}      value        Value to apply.
- * @param {HTMLElement} current      The live root node to apply the element
- *                                   tree to.
- * @param {string}      multilineTag Multiline tag.
+ * @param {Object}      $1 Named arguments.
+ * @param {Object}      $1.value Value to apply.
+ * @param {HTMLElement} $1.current The live root node to apply the element tree to.
+ * @param {?string}      $1.multilineTag Multiline tag.
+ * @param {?Array}       $1.multilineWrapperTags Tags where lines can be found if nesting is possible.
+ * @param {?Array}       $1.prepareEditableTree Functions to prepare the editable tree.
  */
 export function apply( {
 	value,
diff --git a/packages/rich-text/src/to-html-string.js b/packages/rich-text/src/to-html-string.js
index 324dd2d65d287..b5e4911382731 100644
--- a/packages/rich-text/src/to-html-string.js
+++ b/packages/rich-text/src/to-html-string.js
@@ -20,8 +20,8 @@ import { toTree } from './to-tree';
  *
  * @param {Object} $1                      Named argements.
  * @param {Object} $1.value                Rich text value.
- * @param {string} $1.multilineTag         Multiline tag.
- * @param {Array}  $1.multilineWrapperTags Tags where lines can be found if
+ * @param {?string} $1.multilineTag         Multiline tag.
+ * @param {?Array}  $1.multilineWrapperTags Tags where lines can be found if
  *                                         nesting is possible.
  *
  * @return {string} HTML string.

From e984ec364d22aaa42a12a52a85dddfaa2ccfbddb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 17:16:34 +0100
Subject: [PATCH 07/24] Do not document unstable APIs

---
 bin/generate-docs.sh         | 2 +-
 packages/rich-text/README.md | 6 ------
 2 files changed, 1 insertion(+), 7 deletions(-)

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
index 6dd44ab3bcda5..4ad4d645aeffb 100755
--- a/bin/generate-docs.sh
+++ b/bin/generate-docs.sh
@@ -7,5 +7,5 @@ declare -a packages=(
 
 for package in "${packages[@]}"
 do
-	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token;
+	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token --ignore ^unstable;
 done
diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 74173d0f413ac..31e62ce21f56d 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -514,12 +514,6 @@ Unregisters a format.
 
 `?WPFormat` The previous format value, if it has been successfully unregistered; otherwise `undefined`.
 
-### unstableToDom
-
-[src/index.js#L27-L27](src/index.js#L27-L27)
-
-Undocumented declaration.
-
 
 <!-- END TOKEN(Autogenerated API docs) -->
 

From e81f80dbb9fbbd2ed21a29fd0a3eab114ddfa663 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 23:28:39 +0100
Subject: [PATCH 08/24] Remove unstable param

---
 packages/rich-text/README.md     | 1 -
 packages/rich-text/src/to-dom.js | 1 -
 2 files changed, 2 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 31e62ce21f56d..c86192406c688 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -31,7 +31,6 @@ text separated by two new lines will be wrapped in an `Element` of that type.
 -   **$1.current** `HTMLElement`: The live root node to apply the element tree to.
 -   **$1.multilineTag** `?string`: Multiline tag.
 -   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
--   **$1.prepareEditableTree** `?Array`: Functions to prepare the editable tree.
 
 ### applyFormat
 
diff --git a/packages/rich-text/src/to-dom.js b/packages/rich-text/src/to-dom.js
index 524be4f4eb518..0bf42a62e324c 100644
--- a/packages/rich-text/src/to-dom.js
+++ b/packages/rich-text/src/to-dom.js
@@ -169,7 +169,6 @@ export function toDom( {
  * @param {HTMLElement} $1.current The live root node to apply the element tree to.
  * @param {?string}      $1.multilineTag Multiline tag.
  * @param {?Array}       $1.multilineWrapperTags Tags where lines can be found if nesting is possible.
- * @param {?Array}       $1.prepareEditableTree Functions to prepare the editable tree.
  */
 export function apply( {
 	value,

From e4ac9b0472432a267493204b372f50631dc914df Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Mon, 4 Mar 2019 23:45:16 +0100
Subject: [PATCH 09/24] Ignore apply and changeListType symbols

---
 bin/generate-docs.sh         |  2 +-
 packages/rich-text/README.md | 34 ----------------------------------
 2 files changed, 1 insertion(+), 35 deletions(-)

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
index 4ad4d645aeffb..fb8ac3d722a3f 100755
--- a/bin/generate-docs.sh
+++ b/bin/generate-docs.sh
@@ -7,5 +7,5 @@ declare -a packages=(
 
 for package in "${packages[@]}"
 do
-	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token --ignore ^unstable;
+	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token --ignore "^unstable|^apply$|^changeListType$";
 done
diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index c86192406c688..04f80c2b0d5e6 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -16,22 +16,6 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 <!-- START TOKEN(Autogenerated API docs) -->
 
-### apply
-
-[src/index.js#L27-L27](src/index.js#L27-L27)
-
-Create an `Element` tree from a Rich Text value and applies the difference to
-the `Element` tree contained by `current`. If a `multilineTag` is provided,
-text separated by two new lines will be wrapped in an `Element` of that type.
-
-**Parameters**
-
--   **$1** `Object`: Named arguments.
--   **$1.value** `Object`: Value to apply.
--   **$1.current** `HTMLElement`: The live root node to apply the element tree to.
--   **$1.multilineTag** `?string`: Multiline tag.
--   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
-
 ### applyFormat
 
 [src/index.js#L6-L6](src/index.js#L6-L6)
@@ -51,24 +35,6 @@ provided.
 
 `Object` A new value with the format applied.
 
-### changeListType
-
-[src/index.js#L34-L34](src/index.js#L34-L34)
-
-Changes the list type of the selected indented list, if any. Looks at the
-currently selected list item and takes the parent list, then changes the list
-type of this list. When multiple lines are selected, the parent lists are
-takes and changed.
-
-**Parameters**
-
--   **value** `Object`: Value to change.
--   **newFormat** `Object`: The new list format object. Choose between `{ type: 'ol' }` and `{ type: 'ul' }`.
-
-**Returns**
-
-`Object` The changed value.
-
 ### charAt
 
 [src/index.js#L7-L7](src/index.js#L7-L7)

From e9dec205e4e0991635ff1020362c06ea825fd215 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 5 Mar 2019 02:49:58 +0100
Subject: [PATCH 10/24] Use new script

---
 bin/generate-docs.sh  | 11 -----------
 bin/update-readmes.js | 23 +++++++++++++++++++----
 2 files changed, 19 insertions(+), 15 deletions(-)
 delete mode 100755 bin/generate-docs.sh

diff --git a/bin/generate-docs.sh b/bin/generate-docs.sh
deleted file mode 100755
index fb8ac3d722a3f..0000000000000
--- a/bin/generate-docs.sh
+++ /dev/null
@@ -1,11 +0,0 @@
-#!/bin/bash
-
-declare -a packages=(
-	"e2e-test-utils"
-	"rich-text"
-)
-
-for package in "${packages[@]}"
-do
-	npx docgen packages/${package}/src/index.js --output packages/${package}/README.md --to-token --ignore "^unstable|^apply$|^changeListType$";
-done
diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index 6f1efc62ff5a8..0336cfa5bb591 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -27,21 +27,36 @@ const packages = [
 	//'plugins',
 	//'priority-queue',
 	//'redux-routine',
-	//'rich-text',
+	'rich-text',
 	//'shortcode',
 	//'url',
 	//'viewport',
 	//'wordcount',
 ];
 
-let aggregatedExitCode = 0;
-packages.forEach( ( packageName ) => {
-	const args = [
+const getArgsForPackage = ( packageName ) => {
+	const defaultArgs = [
 		`packages/${ packageName }/src/index.js`,
 		`--output packages/${ packageName }/README.md`,
 		'--to-token',
 		'--ignore "unstable|experimental"',
 	];
+
+	const argsForPackage = {
+		'rich-text': [
+			`packages/${ packageName }/src/index.js`,
+			`--output packages/${ packageName }/README.md`,
+			'--to-token',
+			'--ignore "unstable|experimental|^apply$|^changeListType$"',
+		],
+	};
+
+	return argsForPackage[ packageName ] || defaultArgs;
+};
+
+let aggregatedExitCode = 0;
+packages.forEach( ( packageName ) => {
+	const args = getArgsForPackage( packageName );
 	const pathToDocGen = path.join( __dirname, '..', 'node_modules', '.bin', 'docgen' );
 	const { status, stderr } = childProcess.spawnSync(
 		pathToDocGen,

From 7c533befe0d7a27c4caf3d5cd22b72adb6aff0a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 5 Mar 2019 12:16:29 +0100
Subject: [PATCH 11/24] Update output

---
 packages/rich-text/README.md | 57 ++++++++++++++++++------------------
 1 file changed, 28 insertions(+), 29 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 04f80c2b0d5e6..8575755f2425a 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -33,7 +33,7 @@ provided.
 
 **Returns**
 
-`Object` A new value with the format applied.
+`Object`: A new value with the format applied.
 
 ### charAt
 
@@ -49,7 +49,7 @@ character was found.
 
 **Returns**
 
-`?string` A one character long string, or undefined.
+`?string`: A one character long string, or undefined.
 
 ### concat
 
@@ -64,7 +64,7 @@ Combine all Rich Text values into one. This is similar to
 
 **Returns**
 
-`Object` A new value combining all given records.
+`Object`: A new value combining all given records.
 
 ### create
 
@@ -89,7 +89,7 @@ be used to filter out content.
 
 **Returns**
 
-`Object` A rich text value.
+`Object`: A rich text value.
 
 ### getActiveFormat
 
@@ -107,7 +107,7 @@ is no format at the selection.
 
 **Returns**
 
-`?Object` Active format object of the specified type, or undefined.
+`?Object`: Active format object of the specified type, or undefined.
 
 ### getSelectionEnd
 
@@ -123,7 +123,7 @@ index.
 
 **Returns**
 
-`?number` Index where the selection ends.
+`?number`: Index where the selection ends.
 
 ### getSelectionStart
 
@@ -139,7 +139,7 @@ index.
 
 **Returns**
 
-`?number` Index where the selection starts.
+`?number`: Index where the selection starts.
 
 ### getTextContent
 
@@ -154,7 +154,7 @@ Get the textual content of a Rich Text value. This is similar to
 
 **Returns**
 
-`string` The text content.
+`string`: The text content.
 
 ### indentListItems
 
@@ -169,7 +169,7 @@ Indents any selected list items if possible.
 
 **Returns**
 
-`Object` The changed value.
+`Object`: The changed value.
 
 ### insert
 
@@ -189,14 +189,13 @@ none are provided.
 
 **Returns**
 
-`Object` A new value with the value inserted.
+`Object`: A new value with the value inserted.
 
 ### insertLineBreak
 
 [src/index.js#L22-L22](src/index.js#L22-L22)
 
-Inserts a line break at the given or selected position. Inserts two line
-breaks if at the end of a line.
+Inserts a line break at the given or selected position.
 
 **Parameters**
 
@@ -204,7 +203,7 @@ breaks if at the end of a line.
 
 **Returns**
 
-`Object` The value with the line break(s) inserted.
+`Object`: The value with the line break inserted.
 
 ### insertLineSeparator
 
@@ -222,7 +221,7 @@ removed. Indices are retrieved from the selection if none are provided.
 
 **Returns**
 
-`Object` A new value with the value inserted.
+`Object`: A new value with the value inserted.
 
 ### insertObject
 
@@ -241,7 +240,7 @@ removed. Indices are retrieved from the selection if none are provided.
 
 **Returns**
 
-`Object` A new value with the object inserted.
+`Object`: A new value with the object inserted.
 
 ### isCollapsed
 
@@ -258,7 +257,7 @@ is no selection, `undefined` will be returned. This is similar to
 
 **Returns**
 
-`?boolean` True if the selection is collapsed, false if not, undefined if there is no selection.
+`?boolean`: True if the selection is collapsed, false if not, undefined if there is no selection.
 
 ### isEmpty
 
@@ -273,7 +272,7 @@ objects (such as images).
 
 **Returns**
 
-`boolean` True if the value is empty, false if not.
+`boolean`: True if the value is empty, false if not.
 
 ### isEmptyLine
 
@@ -288,7 +287,7 @@ multiline value.
 
 **Returns**
 
-`boolean` True if the line is empty, false if not.
+`boolean`: True if the line is empty, false if not.
 
 ### join
 
@@ -305,7 +304,7 @@ string. This is similar to `Array.prototype.join`.
 
 **Returns**
 
-`Object` A new combined value.
+`Object`: A new combined value.
 
 ### LINE_SEPARATOR
 
@@ -325,7 +324,7 @@ Outdents any selected list items if possible.
 
 **Returns**
 
-`Object` The changed value.
+`Object`: The changed value.
 
 ### registerFormatType
 
@@ -341,7 +340,7 @@ behavior.
 
 **Returns**
 
-`?WPFormat` The format, if it has been successfully registered; otherwise `undefined`.
+`?WPFormat`: The format, if it has been successfully registered; otherwise `undefined`.
 
 ### remove
 
@@ -358,7 +357,7 @@ Remove content from a Rich Text value between the given `startIndex` and
 
 **Returns**
 
-`Object` A new value with the content removed.
+`Object`: A new value with the content removed.
 
 ### removeFormat
 
@@ -377,7 +376,7 @@ selection if none are provided.
 
 **Returns**
 
-`Object` A new value with the format applied.
+`Object`: A new value with the format applied.
 
 ### replace
 
@@ -394,7 +393,7 @@ is similar to `String.prototype.replace`.
 
 **Returns**
 
-`Object` A new value with replacements applied.
+`Object`: A new value with replacements applied.
 
 ### slice
 
@@ -412,7 +411,7 @@ retrieved from the selection if none are provided. This is similar to
 
 **Returns**
 
-`Object` A new extracted value.
+`Object`: A new extracted value.
 
 ### split
 
@@ -430,7 +429,7 @@ Indices are retrieved from the selection if none are provided.
 
 **Returns**
 
-`Array` An array of new values.
+`Array`: An array of new values.
 
 ### toggleFormat
 
@@ -445,7 +444,7 @@ Toggles a format object to a Rich Text value at the current selection.
 
 **Returns**
 
-`Object` A new value with the format applied or removed.
+`Object`: A new value with the format applied or removed.
 
 ### toHTMLString
 
@@ -463,7 +462,7 @@ provided, text separated by a line separator will be wrapped in it.
 
 **Returns**
 
-`string` HTML string.
+`string`: HTML string.
 
 ### unregisterFormatType
 
@@ -477,7 +476,7 @@ Unregisters a format.
 
 **Returns**
 
-`?WPFormat` The previous format value, if it has been successfully unregistered; otherwise `undefined`.
+`?WPFormat`: The previous format value, if it has been successfully unregistered; otherwise `undefined`.
 
 
 <!-- END TOKEN(Autogenerated API docs) -->

From 01ec44d1f2c2bd341e76bdae4b7a2719a5b94adc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Tue, 5 Mar 2019 12:19:05 +0100
Subject: [PATCH 12/24] Refactor to use switch

---
 bin/update-readmes.js | 33 ++++++++++++++++-----------------
 1 file changed, 16 insertions(+), 17 deletions(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index 0336cfa5bb591..34ce2a2e2507b 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -35,23 +35,22 @@ const packages = [
 ];
 
 const getArgsForPackage = ( packageName ) => {
-	const defaultArgs = [
-		`packages/${ packageName }/src/index.js`,
-		`--output packages/${ packageName }/README.md`,
-		'--to-token',
-		'--ignore "unstable|experimental"',
-	];
-
-	const argsForPackage = {
-		'rich-text': [
-			`packages/${ packageName }/src/index.js`,
-			`--output packages/${ packageName }/README.md`,
-			'--to-token',
-			'--ignore "unstable|experimental|^apply$|^changeListType$"',
-		],
-	};
-
-	return argsForPackage[ packageName ] || defaultArgs;
+	switch ( packageName ) {
+		case 'rich-text':
+			return [
+				`packages/${ packageName }/src/index.js`,
+				`--output packages/${ packageName }/README.md`,
+				'--to-token',
+				'--ignore "unstable|experimental|^apply$|^changeListType$"',
+			];
+		default:
+			return [
+				`packages/${ packageName }/src/index.js`,
+				`--output packages/${ packageName }/README.md`,
+				'--to-token',
+				'--ignore "unstable|experimental"',
+			];
+	}
 };
 
 let aggregatedExitCode = 0;

From bf921c5746a41ea64cdaf59ddda61f0ef310b8c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Mar 2019 11:44:49 +0100
Subject: [PATCH 13/24] Ignore functions that are about to be removed

---
 bin/update-readmes.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index 34ce2a2e2507b..c903b9be3506f 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -41,7 +41,7 @@ const getArgsForPackage = ( packageName ) => {
 				`packages/${ packageName }/src/index.js`,
 				`--output packages/${ packageName }/README.md`,
 				'--to-token',
-				'--ignore "unstable|experimental|^apply$|^changeListType$"',
+				'--ignore "unstable|experimental|^apply$|^changeListType$|^chartAt$|^getSelectionStart$|^getSelectionEnd$|^insertLineBreak$"',
 			];
 		default:
 			return [

From 24143b76f9ba5c816746d48e394bd7b4035f48b6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Mar 2019 11:46:14 +0100
Subject: [PATCH 14/24] Update docs

---
 packages/rich-text/README.md | 46 ------------------------------------
 1 file changed, 46 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 8575755f2425a..2e57f8c4d3687 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -109,38 +109,6 @@ is no format at the selection.
 
 `?Object`: Active format object of the specified type, or undefined.
 
-### getSelectionEnd
-
-[src/index.js#L11-L11](src/index.js#L11-L11)
-
-Gets the end index of the current selection, or returns `undefined` if no
-selection exists. The selection ends right before the character at this
-index.
-
-**Parameters**
-
--   **value** `Object`: Value to get the selection from.
-
-**Returns**
-
-`?number`: Index where the selection ends.
-
-### getSelectionStart
-
-[src/index.js#L12-L12](src/index.js#L12-L12)
-
-Gets the start index of the current selection, or returns `undefined` if no
-selection exists. The selection starts right before the character at this
-index.
-
-**Parameters**
-
--   **value** `Object`: Value to get the selection from.
-
-**Returns**
-
-`?number`: Index where the selection starts.
-
 ### getTextContent
 
 [src/index.js#L13-L13](src/index.js#L13-L13)
@@ -191,20 +159,6 @@ none are provided.
 
 `Object`: A new value with the value inserted.
 
-### insertLineBreak
-
-[src/index.js#L22-L22](src/index.js#L22-L22)
-
-Inserts a line break at the given or selected position.
-
-**Parameters**
-
--   **value** `Object`: Value to modify.
-
-**Returns**
-
-`Object`: The value with the line break inserted.
-
 ### insertLineSeparator
 
 [src/index.js#L23-L23](src/index.js#L23-L23)

From 9392d60b2fc7fa1bf3aff353bea77de5c88075da Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 12:04:52 +0100
Subject: [PATCH 15/24] Ignore also indentListItem and outdentListItems

---
 bin/update-readmes.js        |  2 +-
 packages/rich-text/README.md | 29 -----------------------------
 2 files changed, 1 insertion(+), 30 deletions(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index c903b9be3506f..8657f5d605c20 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -41,7 +41,7 @@ const getArgsForPackage = ( packageName ) => {
 				`packages/${ packageName }/src/index.js`,
 				`--output packages/${ packageName }/README.md`,
 				'--to-token',
-				'--ignore "unstable|experimental|^apply$|^changeListType$|^chartAt$|^getSelectionStart$|^getSelectionEnd$|^insertLineBreak$"',
+				'--ignore "unstable|experimental|^apply$|^changeListType$|^chartAt$|^getSelectionStart$|^getSelectionEnd$|^indentListItems$|^insertLineBreak$|^outdentListItems$"',
 			];
 		default:
 			return [
diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 2e57f8c4d3687..012ca06e78182 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -124,21 +124,6 @@ Get the textual content of a Rich Text value. This is similar to
 
 `string`: The text content.
 
-### indentListItems
-
-[src/index.js#L32-L32](src/index.js#L32-L32)
-
-Indents any selected list items if possible.
-
-**Parameters**
-
--   **value** `Object`: Value to change.
--   **rootFormat** `Object`: 
-
-**Returns**
-
-`Object`: The changed value.
-
 ### insert
 
 [src/index.js#L21-L21](src/index.js#L21-L21)
@@ -266,20 +251,6 @@ string. This is similar to `Array.prototype.join`.
 
 Undocumented declaration.
 
-### outdentListItems
-
-[src/index.js#L33-L33](src/index.js#L33-L33)
-
-Outdents any selected list items if possible.
-
-**Parameters**
-
--   **value** `Object`: Value to change.
-
-**Returns**
-
-`Object`: The changed value.
-
 ### registerFormatType
 
 [src/index.js#L17-L17](src/index.js#L17-L17)

From 059d618e016b3bbf8b844ed7f5e4c05195a78e35 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 13:30:50 +0100
Subject: [PATCH 16/24] Fix typo

---
 bin/update-readmes.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index 8657f5d605c20..8aa4c2feed439 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -41,7 +41,7 @@ const getArgsForPackage = ( packageName ) => {
 				`packages/${ packageName }/src/index.js`,
 				`--output packages/${ packageName }/README.md`,
 				'--to-token',
-				'--ignore "unstable|experimental|^apply$|^changeListType$|^chartAt$|^getSelectionStart$|^getSelectionEnd$|^indentListItems$|^insertLineBreak$|^outdentListItems$"',
+				'--ignore "unstable|experimental|^apply$|^changeListType$|^charAt$|^getSelectionStart$|^getSelectionEnd$|^indentListItems$|^insertLineBreak$|^outdentListItems$"',
 			];
 		default:
 			return [

From 156d45da48af129395a33ce6a30edd3ae338a2fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 13:31:09 +0100
Subject: [PATCH 17/24] Update docs

- Fix return undefined or type: should be "{type|undefined}", not "{?type}".
- Fix optional type: should be "{type} [param]", not "{?type} param".
- Fix list of undocumented symbols.
- Updated JSDoc from old README (added new params, etc).
---
 packages/rich-text/README.md                  | 86 ++++++++-----------
 packages/rich-text/src/apply-format.js        |  8 +-
 packages/rich-text/src/char-at.js             |  2 +-
 packages/rich-text/src/create.js              | 14 +--
 packages/rich-text/src/get-active-format.js   |  2 +-
 packages/rich-text/src/get-selection-end.js   |  2 +-
 packages/rich-text/src/get-selection-start.js |  2 +-
 packages/rich-text/src/indent-list-items.js   |  2 +-
 .../rich-text/src/insert-line-separator.js    |  6 +-
 packages/rich-text/src/insert-object.js       |  4 +-
 packages/rich-text/src/insert.js              |  6 +-
 packages/rich-text/src/is-collapsed.js        |  4 +-
 packages/rich-text/src/join.js                |  4 +-
 .../rich-text/src/register-format-type.js     | 12 ++-
 packages/rich-text/src/remove-format.js       |  8 +-
 packages/rich-text/src/remove.js              |  6 +-
 packages/rich-text/src/slice.js               |  6 +-
 packages/rich-text/src/special-characters.js  |  3 +
 packages/rich-text/src/split.js               |  6 +-
 packages/rich-text/src/to-dom.js              | 10 +--
 packages/rich-text/src/to-html-string.js      | 10 +--
 packages/rich-text/src/toggle-format.js       |  4 +-
 .../rich-text/src/unregister-format-type.js   |  4 +-
 23 files changed, 103 insertions(+), 108 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 012ca06e78182..407dfb19d7c34 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -12,7 +12,7 @@ npm install @wordpress/rich-text
 
 _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using [core-js](https://github.com/zloirock/core-js) or [@babel/polyfill](https://babeljs.io/docs/en/next/babel-polyfill) will add support for these methods. Learn more about it in [Babel docs](https://babeljs.io/docs/en/next/caveats)._
 
-## Usage
+## API
 
 <!-- START TOKEN(Autogenerated API docs) -->
 
@@ -28,29 +28,13 @@ provided.
 
 -   **value** `Object`: Value to modify.
 -   **format** `Object`: Format to apply.
--   **startIndex** `?number`: Start index.
--   **endIndex** `?number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
 `Object`: A new value with the format applied.
 
-### charAt
-
-[src/index.js#L7-L7](src/index.js#L7-L7)
-
-Gets the character at the specified index, or returns `undefined` if no
-character was found.
-
-**Parameters**
-
--   **value** `Object`: Value to get the character from.
--   **index** `string`: Index to use.
-
-**Returns**
-
-`?string`: A one character long string, or undefined.
-
 ### concat
 
 [src/index.js#L8-L8](src/index.js#L8-L8)
@@ -79,13 +63,13 @@ be used to filter out content.
 
 **Parameters**
 
--   **$1** `?Object`: Optional named argements.
--   **$1.element** `?Element`: Element to create value from.
--   **$1.text** `?string`: Text to create value from.
--   **$1.html** `?string`: HTML to create value from.
--   **$1.range** `?Range`: Range to create value from.
--   **$1.multilineTag** `?string`: Multiline tag if the structure is multiline.
--   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
+-   **$1** `[Object]`: Optional named arguments.
+-   **$1.element** `[Element]`: Element to create value from.
+-   **$1.text** `[string]`: Text to create value from.
+-   **$1.html** `[string]`: HTML to create value from.
+-   **$1.range** `[Range]`: Range to create value from.
+-   **$1.multilineTag** `[string]`: Multiline tag if the structure is multiline.
+-   **$1.multilineWrapperTags** `[Array]`: Tags where lines can be found if nesting is possible.
 
 **Returns**
 
@@ -107,7 +91,7 @@ is no format at the selection.
 
 **Returns**
 
-`?Object`: Active format object of the specified type, or undefined.
+`(Object|undefined)`: Active format object of the specified type, or undefined.
 
 ### getTextContent
 
@@ -137,8 +121,8 @@ none are provided.
 
 -   **value** `Object`: Value to modify.
 -   **valueToInsert** `(Object|string)`: Value to insert.
--   **startIndex** `?number`: Start index.
--   **endIndex** `?number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
@@ -155,8 +139,8 @@ removed. Indices are retrieved from the selection if none are provided.
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
@@ -174,8 +158,8 @@ removed. Indices are retrieved from the selection if none are provided.
 
 -   **value** `Object`: Value to modify.
 -   **formatToInsert** `Object`: Format to insert as object.
--   **startIndex** `number`: Start index.
--   **endIndex** `number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
@@ -196,7 +180,7 @@ is no selection, `undefined` will be returned. This is similar to
 
 **Returns**
 
-`?boolean`: True if the selection is collapsed, false if not, undefined if there is no selection.
+`(boolean|undefined)`: True if the selection is collapsed, false if not, undefined if there is no selection.
 
 ### isEmpty
 
@@ -238,8 +222,8 @@ string. This is similar to `Array.prototype.join`.
 
 **Parameters**
 
--   **values** `Array`: An array of values to join.
--   **separator** `?(string|Object)`: Separator string or value.
+-   **values** `Array<Object>`: An array of values to join.
+-   **separator** `[(string|Object)]`: Separator string or value.
 
 **Returns**
 
@@ -249,7 +233,7 @@ string. This is similar to `Array.prototype.join`.
 
 [src/index.js#L30-L30](src/index.js#L30-L30)
 
-Undocumented declaration.
+Keycode for line separator.
 
 ### registerFormatType
 
@@ -262,10 +246,14 @@ behavior.
 
 -   **name** `string`: Format name.
 -   **settings** `Object`: Format settings.
+-   **settings.tagName** `string`: The HTML tag this format will wrap the selection with.
+-   **settings.className** `[string]`: A class to match the format.
+-   **settings.title** `string`: Name of the format.
+-   **settings.edit** `Function`: Should return a component for the user to interact with the new registered format.
 
 **Returns**
 
-`?WPFormat`: The format, if it has been successfully registered; otherwise `undefined`.
+`(WPFormat|undefined)`: The format, if it has been successfully registered; otherwise `undefined`.
 
 ### remove
 
@@ -277,8 +265,8 @@ Remove content from a Rich Text value between the given `startIndex` and
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **startIndex** `?number`: Start index.
--   **endIndex** `?number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
@@ -296,8 +284,8 @@ selection if none are provided.
 
 -   **value** `Object`: Value to modify.
 -   **formatType** `string`: Format type to remove.
--   **startIndex** `?number`: Start index.
--   **endIndex** `?number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
@@ -331,8 +319,8 @@ retrieved from the selection if none are provided. This is similar to
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **startIndex** `?number`: Start index.
--   **endIndex** `?number`: End index.
+-   **startIndex** `[number]`: Start index.
+-   **endIndex** `[number]`: End index.
 
 **Returns**
 
@@ -349,8 +337,8 @@ Indices are retrieved from the selection if none are provided.
 **Parameters**
 
 -   **value** `Object`: Value to modify.
--   **string** `?(number|string)`: Start index, or string at which to split.
--   **endStr** `?number`: End index.
+-   **string** `[(number|string)]`: Start index, or string at which to split.
+-   **endStr** `[number]`: End index.
 
 **Returns**
 
@@ -382,8 +370,8 @@ provided, text separated by a line separator will be wrapped in it.
 
 -   **$1** `Object`: Named argements.
 -   **$1.value** `Object`: Rich text value.
--   **$1.multilineTag** `?string`: Multiline tag.
--   **$1.multilineWrapperTags** `?Array`: Tags where lines can be found if nesting is possible.
+-   **$1.multilineTag** `[string]`: Multiline tag.
+-   **$1.multilineWrapperTags** `[Array]`: Tags where lines can be found if nesting is possible.
 
 **Returns**
 
@@ -401,7 +389,7 @@ Unregisters a format.
 
 **Returns**
 
-`?WPFormat`: The previous format value, if it has been successfully unregistered; otherwise `undefined`.
+`(WPFormat|undefined)`: The previous format value, if it has been successfully unregistered; otherwise `undefined`.
 
 
 <!-- END TOKEN(Autogenerated API docs) -->
diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js
index 15c6a5e1df022..f9354c8dbba79 100644
--- a/packages/rich-text/src/apply-format.js
+++ b/packages/rich-text/src/apply-format.js
@@ -15,10 +15,10 @@ import { normaliseFormats } from './normalise-formats';
  * given `endIndex`. Indices are retrieved from the selection if none are
  * provided.
  *
- * @param {Object} value      Value to modify.
- * @param {Object} format     Format to apply.
- * @param {?number} startIndex Start index.
- * @param {?number} endIndex   End index.
+ * @param {Object}  value       Value to modify.
+ * @param {Object}  format      Format to apply.
+ * @param {number} [startIndex] Start index.
+ * @param {number} [endIndex]   End index.
  *
  * @return {Object} A new value with the format applied.
  */
diff --git a/packages/rich-text/src/char-at.js b/packages/rich-text/src/char-at.js
index 6f04c2e2ac1aa..e68d3b6a5a5ac 100644
--- a/packages/rich-text/src/char-at.js
+++ b/packages/rich-text/src/char-at.js
@@ -5,7 +5,7 @@
  * @param {Object} value Value to get the character from.
  * @param {string} index Index to use.
  *
- * @return {?string} A one character long string, or undefined.
+ * @return {string|undefined} A one character long string, or undefined.
  */
 export function charAt( { text }, index ) {
 	return text[ index ];
diff --git a/packages/rich-text/src/create.js b/packages/rich-text/src/create.js
index 82348bbd4fa8a..9fa677828209d 100644
--- a/packages/rich-text/src/create.js
+++ b/packages/rich-text/src/create.js
@@ -89,14 +89,14 @@ function toFormat( { type, attributes } ) {
  * `multilineTag` will be separated by two newlines. The optional functions can
  * be used to filter out content.
  *
- * @param {?Object}   $1                      Optional named argements.
- * @param {?Element}  $1.element              Element to create value from.
- * @param {?string}   $1.text                 Text to create value from.
- * @param {?string}   $1.html                 HTML to create value from.
- * @param {?Range}    $1.range                Range to create value from.
- * @param {?string}   $1.multilineTag         Multiline tag if the structure is
+ * @param {Object}  [$1]                      Optional named arguments.
+ * @param {Element} [$1.element]              Element to create value from.
+ * @param {string}  [$1.text]                 Text to create value from.
+ * @param {string}  [$1.html]                 HTML to create value from.
+ * @param {Range}   [$1.range]                Range to create value from.
+ * @param {string}  [$1.multilineTag]         Multiline tag if the structure is
  *                                            multiline.
- * @param {?Array}    $1.multilineWrapperTags Tags where lines can be found if
+ * @param {Array}   [$1.multilineWrapperTags] Tags where lines can be found if
  *                                            nesting is possible.
  *
  * @return {Object} A rich text value.
diff --git a/packages/rich-text/src/get-active-format.js b/packages/rich-text/src/get-active-format.js
index 89fcb5fc7711c..fd658bf6adc27 100644
--- a/packages/rich-text/src/get-active-format.js
+++ b/packages/rich-text/src/get-active-format.js
@@ -19,7 +19,7 @@ import { getActiveFormats } from './get-active-formats';
  * @param {Object} value      Value to inspect.
  * @param {string} formatType Format type to look for.
  *
- * @return {?Object} Active format object of the specified type, or undefined.
+ * @return {Object|undefined} Active format object of the specified type, or undefined.
  */
 export function getActiveFormat( value, formatType ) {
 	return find( getActiveFormats( value ), { type: formatType } );
diff --git a/packages/rich-text/src/get-selection-end.js b/packages/rich-text/src/get-selection-end.js
index 90dee341391c1..8154a48b451fb 100644
--- a/packages/rich-text/src/get-selection-end.js
+++ b/packages/rich-text/src/get-selection-end.js
@@ -5,7 +5,7 @@
  *
  * @param {Object} value Value to get the selection from.
  *
- * @return {?number} Index where the selection ends.
+ * @return {number|undefined} Index where the selection ends.
  */
 export function getSelectionEnd( { end } ) {
 	return end;
diff --git a/packages/rich-text/src/get-selection-start.js b/packages/rich-text/src/get-selection-start.js
index 948d380052314..442d84d308691 100644
--- a/packages/rich-text/src/get-selection-start.js
+++ b/packages/rich-text/src/get-selection-start.js
@@ -5,7 +5,7 @@
  *
  * @param {Object} value Value to get the selection from.
  *
- * @return {?number} Index where the selection starts.
+ * @return {number|undefined} Index where the selection starts.
  */
 export function getSelectionStart( { start } ) {
 	return start;
diff --git a/packages/rich-text/src/indent-list-items.js b/packages/rich-text/src/indent-list-items.js
index 516b3c85f96ea..1a61bd7db1536 100644
--- a/packages/rich-text/src/indent-list-items.js
+++ b/packages/rich-text/src/indent-list-items.js
@@ -40,7 +40,7 @@ function getTargetLevelLineIndex( { text, formats }, lineIndex ) {
  * Indents any selected list items if possible.
  *
  * @param {Object} value      Value to change.
- * @param {Object} rootFormat
+ * @param {Object} rootFormat Root format.
  *
  * @return {Object} The changed value.
  */
diff --git a/packages/rich-text/src/insert-line-separator.js b/packages/rich-text/src/insert-line-separator.js
index 24174668d25cb..e273c9eea9ac4 100644
--- a/packages/rich-text/src/insert-line-separator.js
+++ b/packages/rich-text/src/insert-line-separator.js
@@ -11,9 +11,9 @@ import { LINE_SEPARATOR } from './special-characters';
  * `startIndex`. Any content between `startIndex` and `endIndex` will be
  * removed. Indices are retrieved from the selection if none are provided.
  *
- * @param {Object} value         Value to modify.
- * @param {number} startIndex    Start index.
- * @param {number} endIndex      End index.
+ * @param {Object} value        Value to modify.
+ * @param {number} [startIndex] Start index.
+ * @param {number} [endIndex]   End index.
  *
  * @return {Object} A new value with the value inserted.
  */
diff --git a/packages/rich-text/src/insert-object.js b/packages/rich-text/src/insert-object.js
index bf67ac3913b73..fcdfc6f897c2d 100644
--- a/packages/rich-text/src/insert-object.js
+++ b/packages/rich-text/src/insert-object.js
@@ -13,8 +13,8 @@ const OBJECT_REPLACEMENT_CHARACTER = '\ufffc';
  *
  * @param {Object} value          Value to modify.
  * @param {Object} formatToInsert Format to insert as object.
- * @param {number} startIndex     Start index.
- * @param {number} endIndex       End index.
+ * @param {number} [startIndex]   Start index.
+ * @param {number} [endIndex]     End index.
  *
  * @return {Object} A new value with the object inserted.
  */
diff --git a/packages/rich-text/src/insert.js b/packages/rich-text/src/insert.js
index abfb1832f0d97..cf46305240fb7 100644
--- a/packages/rich-text/src/insert.js
+++ b/packages/rich-text/src/insert.js
@@ -11,10 +11,10 @@ import { normaliseFormats } from './normalise-formats';
  * and `endIndex` will be removed. Indices are retrieved from the selection if
  * none are provided.
  *
- * @param {Object} value         Value to modify.
+ * @param {Object}        value         Value to modify.
  * @param {Object|string} valueToInsert Value to insert.
- * @param {?number} startIndex    Start index.
- * @param {?number} endIndex      End index.
+ * @param {number}        [startIndex]  Start index.
+ * @param {number}        [endIndex]    End index.
  *
  * @return {Object} A new value with the value inserted.
  */
diff --git a/packages/rich-text/src/is-collapsed.js b/packages/rich-text/src/is-collapsed.js
index 7c1e49b5a7cd4..7014d510377c2 100644
--- a/packages/rich-text/src/is-collapsed.js
+++ b/packages/rich-text/src/is-collapsed.js
@@ -6,8 +6,8 @@
  *
  * @param {Object} value The rich text value to check.
  *
- * @return {?boolean} True if the selection is collapsed, false if not,
- *                    undefined if there is no selection.
+ * @return {boolean|undefined} True if the selection is collapsed, false if not,
+ *                             undefined if there is no selection.
  */
 export function isCollapsed( { start, end } ) {
 	if ( start === undefined || end === undefined ) {
diff --git a/packages/rich-text/src/join.js b/packages/rich-text/src/join.js
index 0dba527e3456f..7784b5962ca53 100644
--- a/packages/rich-text/src/join.js
+++ b/packages/rich-text/src/join.js
@@ -10,8 +10,8 @@ import { normaliseFormats } from './normalise-formats';
  * `separator`, which can be a Rich Text value, HTML string, or plain text
  * string. This is similar to `Array.prototype.join`.
  *
- * @param {Array}         values    An array of values to join.
- * @param {?(string|Object)} separator Separator string or value.
+ * @param {Array<Object>} values      An array of values to join.
+ * @param {string|Object} [separator] Separator string or value.
  *
  * @return {Object} A new combined value.
  */
diff --git a/packages/rich-text/src/register-format-type.js b/packages/rich-text/src/register-format-type.js
index 262812a22b248..8b07559541984 100644
--- a/packages/rich-text/src/register-format-type.js
+++ b/packages/rich-text/src/register-format-type.js
@@ -26,11 +26,15 @@ const EMPTY_ARRAY = [];
  * Registers a new format provided a unique name and an object defining its
  * behavior.
  *
- * @param {string} name     Format name.
- * @param {Object} settings Format settings.
+ * @param {string}   name                 Format name.
+ * @param {Object}   settings             Format settings.
+ * @param {string}   settings.tagName     The HTML tag this format will wrap the selection with.
+ * @param {string}   [settings.className] A class to match the format.
+ * @param {string}   settings.title       Name of the format.
+ * @param {Function} settings.edit        Should return a component for the user to interact with the new registered format.
  *
- * @return {?WPFormat} The format, if it has been successfully registered;
- *                     otherwise `undefined`.
+ * @return {WPFormat|undefined} The format, if it has been successfully registered;
+ *                              otherwise `undefined`.
  */
 export function registerFormatType( name, settings ) {
 	settings = {
diff --git a/packages/rich-text/src/remove-format.js b/packages/rich-text/src/remove-format.js
index 89ccecbbb31b2..be1c92ace7fd4 100644
--- a/packages/rich-text/src/remove-format.js
+++ b/packages/rich-text/src/remove-format.js
@@ -15,10 +15,10 @@ import { normaliseFormats } from './normalise-formats';
  * `startIndex` to the given `endIndex`. Indices are retrieved from the
  * selection if none are provided.
  *
- * @param {Object} value      Value to modify.
- * @param {string} formatType Format type to remove.
- * @param {?number} startIndex Start index.
- * @param {?number} endIndex   End index.
+ * @param {Object} value        Value to modify.
+ * @param {string} formatType   Format type to remove.
+ * @param {number} [startIndex] Start index.
+ * @param {number} [endIndex]   End index.
  *
  * @return {Object} A new value with the format applied.
  */
diff --git a/packages/rich-text/src/remove.js b/packages/rich-text/src/remove.js
index 8557605cc0597..3f91dbf3a7185 100644
--- a/packages/rich-text/src/remove.js
+++ b/packages/rich-text/src/remove.js
@@ -9,9 +9,9 @@ import { create } from './create';
  * Remove content from a Rich Text value between the given `startIndex` and
  * `endIndex`. Indices are retrieved from the selection if none are provided.
  *
- * @param {Object} value      Value to modify.
- * @param {?number} startIndex Start index.
- * @param {?number} endIndex   End index.
+ * @param {Object}  value       Value to modify.
+ * @param {number} [startIndex] Start index.
+ * @param {number} [endIndex]   End index.
  *
  * @return {Object} A new value with the content removed.
  */
diff --git a/packages/rich-text/src/slice.js b/packages/rich-text/src/slice.js
index 768570d1680f0..bb4313dd61309 100644
--- a/packages/rich-text/src/slice.js
+++ b/packages/rich-text/src/slice.js
@@ -3,9 +3,9 @@
  * retrieved from the selection if none are provided. This is similar to
  * `String.prototype.slice`.
  *
- * @param {Object} value       Value to modify.
- * @param {?number} startIndex  Start index.
- * @param {?number} endIndex    End index.
+ * @param {Object} value        Value to modify.
+ * @param {number} [startIndex] Start index.
+ * @param {number} [endIndex]   End index.
  *
  * @return {Object} A new extracted value.
  */
diff --git a/packages/rich-text/src/special-characters.js b/packages/rich-text/src/special-characters.js
index 611869f8dbe56..1589c0b8279e2 100644
--- a/packages/rich-text/src/special-characters.js
+++ b/packages/rich-text/src/special-characters.js
@@ -1,2 +1,5 @@
+/**
+ * Keycode for line separator.
+ */
 export const LINE_SEPARATOR = '\u2028';
 export const OBJECT_REPLACEMENT_CHARACTER = '\ufffc';
diff --git a/packages/rich-text/src/split.js b/packages/rich-text/src/split.js
index 0fc28fdfae612..a300c3ccbcca4 100644
--- a/packages/rich-text/src/split.js
+++ b/packages/rich-text/src/split.js
@@ -9,9 +9,9 @@ import { replace } from './replace';
  * split at the given separator. This is similar to `String.prototype.split`.
  * Indices are retrieved from the selection if none are provided.
  *
- * @param {Object}        value   Value to modify.
- * @param {?(number|string)} string  Start index, or string at which to split.
- * @param {?number}        endStr     End index.
+ * @param {Object}        value    Value to modify.
+ * @param {number|string} [string] Start index, or string at which to split.
+ * @param {number}        [endStr] End index.
  *
  * @return {Array} An array of new values.
  */
diff --git a/packages/rich-text/src/to-dom.js b/packages/rich-text/src/to-dom.js
index 0bf42a62e324c..b81c518468444 100644
--- a/packages/rich-text/src/to-dom.js
+++ b/packages/rich-text/src/to-dom.js
@@ -164,11 +164,11 @@ export function toDom( {
  * the `Element` tree contained by `current`. If a `multilineTag` is provided,
  * text separated by two new lines will be wrapped in an `Element` of that type.
  *
- * @param {Object}      $1 Named arguments.
- * @param {Object}      $1.value Value to apply.
- * @param {HTMLElement} $1.current The live root node to apply the element tree to.
- * @param {?string}      $1.multilineTag Multiline tag.
- * @param {?Array}       $1.multilineWrapperTags Tags where lines can be found if nesting is possible.
+ * @param {Object}      $1                        Named arguments.
+ * @param {Object}      $1.value                  Value to apply.
+ * @param {HTMLElement} $1.current                The live root node to apply the element tree to.
+ * @param {string}      [$1.multilineTag]         Multiline tag.
+ * @param {Array}       [$1.multilineWrapperTags] Tags where lines can be found if nesting is possible.
  */
 export function apply( {
 	value,
diff --git a/packages/rich-text/src/to-html-string.js b/packages/rich-text/src/to-html-string.js
index b5e4911382731..bfed7307a9c13 100644
--- a/packages/rich-text/src/to-html-string.js
+++ b/packages/rich-text/src/to-html-string.js
@@ -18,11 +18,11 @@ import { toTree } from './to-tree';
  * Create an HTML string from a Rich Text value. If a `multilineTag` is
  * provided, text separated by a line separator will be wrapped in it.
  *
- * @param {Object} $1                      Named argements.
- * @param {Object} $1.value                Rich text value.
- * @param {?string} $1.multilineTag         Multiline tag.
- * @param {?Array}  $1.multilineWrapperTags Tags where lines can be found if
- *                                         nesting is possible.
+ * @param {Object}  $1                       Named argements.
+ * @param {Object}  $1.value                 Rich text value.
+ * @param {string} [$1.multilineTag]         Multiline tag.
+ * @param {Array}  [$1.multilineWrapperTags] Tags where lines can be found if
+ *                                           nesting is possible.
  *
  * @return {string} HTML string.
  */
diff --git a/packages/rich-text/src/toggle-format.js b/packages/rich-text/src/toggle-format.js
index 147d9524df246..6e7854dcaa662 100644
--- a/packages/rich-text/src/toggle-format.js
+++ b/packages/rich-text/src/toggle-format.js
@@ -9,8 +9,8 @@ import { applyFormat } from './apply-format';
 /**
  * Toggles a format object to a Rich Text value at the current selection.
  *
- * @param {Object} value      Value to modify.
- * @param {Object} format     Format to apply or remove.
+ * @param {Object} value  Value to modify.
+ * @param {Object} format Format to apply or remove.
  *
  * @return {Object} A new value with the format applied or removed.
  */
diff --git a/packages/rich-text/src/unregister-format-type.js b/packages/rich-text/src/unregister-format-type.js
index cffaa3d025b94..6f6741183ee16 100644
--- a/packages/rich-text/src/unregister-format-type.js
+++ b/packages/rich-text/src/unregister-format-type.js
@@ -9,8 +9,8 @@ import { removeFilter } from '@wordpress/hooks';
  *
  * @param {string} name Format name.
  *
- * @return {?WPFormat} The previous format value, if it has been successfully
- *                     unregistered; otherwise `undefined`.
+ * @return {WPFormat|undefined} The previous format value, if it has been successfully
+ *                              unregistered; otherwise `undefined`.
  */
 export function unregisterFormatType( name ) {
 	const oldFormat = select( 'core/rich-text' ).getFormatType( name );

From 70647bcc39d40777ddb7cf6c9d9ef8fd55caedd0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 13:59:29 +0100
Subject: [PATCH 18/24] Fix comment

---
 packages/rich-text/README.md                 | 2 +-
 packages/rich-text/src/special-characters.js | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index 407dfb19d7c34..a42feafb077d2 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -233,7 +233,7 @@ string. This is similar to `Array.prototype.join`.
 
 [src/index.js#L30-L30](src/index.js#L30-L30)
 
-Keycode for line separator.
+Line separator character.
 
 ### registerFormatType
 
diff --git a/packages/rich-text/src/special-characters.js b/packages/rich-text/src/special-characters.js
index 1589c0b8279e2..5695c40c745b9 100644
--- a/packages/rich-text/src/special-characters.js
+++ b/packages/rich-text/src/special-characters.js
@@ -1,5 +1,5 @@
 /**
- * Keycode for line separator.
+ * Line separator character.
  */
 export const LINE_SEPARATOR = '\u2028';
 export const OBJECT_REPLACEMENT_CHARACTER = '\ufffc';

From 50d18e535337fc8ddf3eef94110c099955fc979a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 14:01:30 +0100
Subject: [PATCH 19/24] Fix spaces

---
 packages/rich-text/src/remove.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/rich-text/src/remove.js b/packages/rich-text/src/remove.js
index 3f91dbf3a7185..f1f14c6deee5e 100644
--- a/packages/rich-text/src/remove.js
+++ b/packages/rich-text/src/remove.js
@@ -9,7 +9,7 @@ import { create } from './create';
  * Remove content from a Rich Text value between the given `startIndex` and
  * `endIndex`. Indices are retrieved from the selection if none are provided.
  *
- * @param {Object}  value       Value to modify.
+ * @param {Object} value       Value to modify.
  * @param {number} [startIndex] Start index.
  * @param {number} [endIndex]   End index.
  *

From 6e4dea795be863b82e3fefe8bd182d882138aed9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 14:03:13 +0100
Subject: [PATCH 20/24] Fix spaces

---
 packages/rich-text/src/apply-format.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js
index f9354c8dbba79..18a431c1230f5 100644
--- a/packages/rich-text/src/apply-format.js
+++ b/packages/rich-text/src/apply-format.js
@@ -15,8 +15,8 @@ import { normaliseFormats } from './normalise-formats';
  * given `endIndex`. Indices are retrieved from the selection if none are
  * provided.
  *
- * @param {Object}  value       Value to modify.
- * @param {Object}  format      Format to apply.
+ * @param {Object} value       Value to modify.
+ * @param {Object} format      Format to apply.
  * @param {number} [startIndex] Start index.
  * @param {number} [endIndex]   End index.
  *

From 665c702042958958f7c3ca9fa04576a27371ee99 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 14:07:00 +0100
Subject: [PATCH 21/24] Ignore more symbols

---
 bin/update-readmes.js        |  2 +-
 packages/rich-text/README.md | 39 ------------------------------------
 2 files changed, 1 insertion(+), 40 deletions(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index 8aa4c2feed439..fb1be92aa4a34 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -41,7 +41,7 @@ const getArgsForPackage = ( packageName ) => {
 				`packages/${ packageName }/src/index.js`,
 				`--output packages/${ packageName }/README.md`,
 				'--to-token',
-				'--ignore "unstable|experimental|^apply$|^changeListType$|^charAt$|^getSelectionStart$|^getSelectionEnd$|^indentListItems$|^insertLineBreak$|^outdentListItems$"',
+				'--ignore "unstable|experimental|^apply$|^changeListType$|^charAt$|^getSelectionStart$|^getSelectionEnd$|^indentListItems$|^insertLineBreak$|^insertLineSeparator$|^isEmptyLine$|^LINE_SEPARATOR$|^outdentListItems$"',
 			];
 		default:
 			return [
diff --git a/packages/rich-text/README.md b/packages/rich-text/README.md
index a42feafb077d2..0ac85d85b640d 100644
--- a/packages/rich-text/README.md
+++ b/packages/rich-text/README.md
@@ -128,24 +128,6 @@ none are provided.
 
 `Object`: A new value with the value inserted.
 
-### insertLineSeparator
-
-[src/index.js#L23-L23](src/index.js#L23-L23)
-
-Insert a line break character into a Rich Text value at the given
-`startIndex`. Any content between `startIndex` and `endIndex` will be
-removed. Indices are retrieved from the selection if none are provided.
-
-**Parameters**
-
--   **value** `Object`: Value to modify.
--   **startIndex** `[number]`: Start index.
--   **endIndex** `[number]`: End index.
-
-**Returns**
-
-`Object`: A new value with the value inserted.
-
 ### insertObject
 
 [src/index.js#L24-L24](src/index.js#L24-L24)
@@ -197,21 +179,6 @@ objects (such as images).
 
 `boolean`: True if the value is empty, false if not.
 
-### isEmptyLine
-
-[src/index.js#L15-L15](src/index.js#L15-L15)
-
-Check if the current collapsed selection is on an empty line in case of a
-multiline value.
-
-**Parameters**
-
--   **value** `Object`: Value te check.
-
-**Returns**
-
-`boolean`: True if the line is empty, false if not.
-
 ### join
 
 [src/index.js#L16-L16](src/index.js#L16-L16)
@@ -229,12 +196,6 @@ string. This is similar to `Array.prototype.join`.
 
 `Object`: A new combined value.
 
-### LINE_SEPARATOR
-
-[src/index.js#L30-L30](src/index.js#L30-L30)
-
-Line separator character.
-
 ### registerFormatType
 
 [src/index.js#L17-L17](src/index.js#L17-L17)

From 02ba0b30617a942c7d3fc26c3279c852c8150214 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 14:08:55 +0100
Subject: [PATCH 22/24] fix spaces

---
 packages/rich-text/src/apply-format.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js
index 18a431c1230f5..8134cd8d742a9 100644
--- a/packages/rich-text/src/apply-format.js
+++ b/packages/rich-text/src/apply-format.js
@@ -15,8 +15,8 @@ import { normaliseFormats } from './normalise-formats';
  * given `endIndex`. Indices are retrieved from the selection if none are
  * provided.
  *
- * @param {Object} value       Value to modify.
- * @param {Object} format      Format to apply.
+ * @param {Object} value        Value to modify.
+ * @param {Object} format       Format to apply.
  * @param {number} [startIndex] Start index.
  * @param {number} [endIndex]   End index.
  *

From 98f04d49d7b7cba6be42672434fb08c20c680342 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 14:10:19 +0100
Subject: [PATCH 23/24] fix spaces

---
 packages/rich-text/src/remove.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/rich-text/src/remove.js b/packages/rich-text/src/remove.js
index f1f14c6deee5e..c3af472167baa 100644
--- a/packages/rich-text/src/remove.js
+++ b/packages/rich-text/src/remove.js
@@ -9,7 +9,7 @@ import { create } from './create';
  * Remove content from a Rich Text value between the given `startIndex` and
  * `endIndex`. Indices are retrieved from the selection if none are provided.
  *
- * @param {Object} value       Value to modify.
+ * @param {Object} value        Value to modify.
  * @param {number} [startIndex] Start index.
  * @param {number} [endIndex]   End index.
  *

From e4242d40b6c6a135de487cd1ac3c3aa822e088f6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Thu, 7 Mar 2019 14:17:53 +0100
Subject: [PATCH 24/24] fix spaces

---
 packages/rich-text/src/to-html-string.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/rich-text/src/to-html-string.js b/packages/rich-text/src/to-html-string.js
index bfed7307a9c13..0ba36e62510a3 100644
--- a/packages/rich-text/src/to-html-string.js
+++ b/packages/rich-text/src/to-html-string.js
@@ -18,8 +18,8 @@ import { toTree } from './to-tree';
  * Create an HTML string from a Rich Text value. If a `multilineTag` is
  * provided, text separated by a line separator will be wrapped in it.
  *
- * @param {Object}  $1                       Named argements.
- * @param {Object}  $1.value                 Rich text value.
+ * @param {Object} $1                        Named argements.
+ * @param {Object} $1.value                  Rich text value.
  * @param {string} [$1.multilineTag]         Multiline tag.
  * @param {Array}  [$1.multilineWrapperTags] Tags where lines can be found if
  *                                           nesting is possible.