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