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

@@ -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) -->

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.
  */

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 ];

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.

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 } );

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;

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;

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.
  */

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.
  */

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.
  */

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.
  */

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 ) {

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.
  */

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 = {

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.
  */