From 22c60f5926c975488d47597fbfe7a411322e8804 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= 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 00000000000000..c7ec1314d9b519 --- /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?= 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 c7ec1314d9b519..afdebea2977d40 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?= 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 afdebea2977d40..00000000000000 --- 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?= 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 be3d703b2678f6..41be6dc6aa6919 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 + -```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 -``` +[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, ?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 -``` -Combine all Rich Text values into one. This is similar to `String.prototype.concat`. +

Code is Poetry.

diff --git a/packages/rich-text/package.json b/packages/rich-text/package.json index 824ce28ef1d183..690204c53f02c9 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?= 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 00000000000000..6dd44ab3bcda59 --- /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 690204c53f02c9..824ce28ef1d183 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?= 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 41be6dc6aa6919..74173d0f413ac9 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 271be1176931df..15c6a5e1df0228 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 10c2ec0e9621ac..abfb1832f0d977 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 c2e3c103b0674c..0dba527e3456f1 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 d6f2890f3afaf4..89ccecbbb31b2d 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 de4241ad301e69..8557605cc05978 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 3a54642b98cc7f..768570d1680f01 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 d8b40b5aafb75b..0fc28fdfae612a 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 987849172bf5f9..524be4f4eb518e 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 324dd2d65d2871..b5e49113827311 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?= 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 6dd44ab3bcda59..4ad4d645aeffbb 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 74173d0f413ac9..31e62ce21f56d1 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. - From e81f80dbb9fbbd2ed21a29fd0a3eab114ddfa663 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= 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 31e62ce21f56d1..c86192406c688f 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 524be4f4eb518e..0bf42a62e324c8 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?= 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 4ad4d645aeffbb..fb8ac3d722a3fb 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 c86192406c688f..04f80c2b0d5e63 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 -### 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?= 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 fb8ac3d722a3fb..00000000000000 --- 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 6f1efc62ff5a8d..0336cfa5bb5914 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?= 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 04f80c2b0d5e63..8575755f2425aa 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`. From 01ec44d1f2c2bd341e76bdae4b7a2719a5b94adc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= 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 0336cfa5bb5914..34ce2a2e2507b4 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?= 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 34ce2a2e2507b4..c903b9be3506f9 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?= 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 8575755f2425aa..2e57f8c4d36877 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?= 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 c903b9be3506f9..8657f5d605c20e 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 2e57f8c4d36877..012ca06e78182e 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?= 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 8657f5d605c20e..8aa4c2feed4392 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?= 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 012ca06e78182e..407dfb19d7c346 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 @@ -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`: 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`. diff --git a/packages/rich-text/src/apply-format.js b/packages/rich-text/src/apply-format.js index 15c6a5e1df0228..f9354c8dbba79f 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 6f04c2e2ac1aa4..e68d3b6a5a5ac9 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 82348bbd4fa8aa..9fa677828209de 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 89fcb5fc7711c6..fd658bf6adc273 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 90dee341391c18..8154a48b451fbc 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 948d3800523149..442d84d308691c 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 516b3c85f96ea2..1a61bd7db15360 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 24174668d25cb8..e273c9eea9ac48 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 bf67ac3913b739..fcdfc6f897c2dd 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 abfb1832f0d977..cf46305240fb70 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 7c1e49b5a7cd42..7014d510377c29 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 0dba527e3456f1..7784b5962ca536 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} 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 262812a22b248f..8b075595419845 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 89ccecbbb31b2d..be1c92ace7fd43 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 8557605cc05978..3f91dbf3a71855 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 768570d1680f01..bb4313dd61309a 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 611869f8dbe565..1589c0b8279e26 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 0fc28fdfae612a..a300c3ccbcca4a 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 0bf42a62e324c8..b81c5184684440 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 b5e49113827311..bfed7307a9c13c 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 147d9524df246b..6e7854dcaa6626 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 cffaa3d025b94b..6f6741183ee164 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?= 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 407dfb19d7c346..a42feafb077d2a 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 1589c0b8279e26..5695c40c745b96 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?= 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 3f91dbf3a71855..f1f14c6deee5e5 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?= 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 f9354c8dbba79f..18a431c1230f5e 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?= 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 8aa4c2feed4392..fb1be92aa4a34b 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 a42feafb077d2a..0ac85d85b640d1 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?= 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 18a431c1230f5e..8134cd8d742a99 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?= 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 f1f14c6deee5e5..c3af472167baa8 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?= 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 bfed7307a9c13c..0ba36e62510a35 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.