From 9dd9d5f66b6be07be3174528cb7555040177159f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Fri, 1 Mar 2019 20:03:07 +0100 Subject: [PATCH 1/3] Autogenerated docs and setup for escape-html --- packages/escape-html/README.md | 114 ++++++++++++++++++++++++++++++ packages/escape-html/package.json | 6 ++ 2 files changed, 120 insertions(+) diff --git a/packages/escape-html/README.md b/packages/escape-html/README.md index 310034d07cd8e..f5ceb1c685fc4 100644 --- a/packages/escape-html/README.md +++ b/packages/escape-html/README.md @@ -12,4 +12,118 @@ npm install @wordpress/escape-html _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)._ +## API + + + +### escapeAmpersand + +[src/index.js#L28-L30](src/index.js#L28-L30) + +Returns a string with ampersands escaped. Note that this is an imperfect +implementation, where only ampersands which do not appear as a pattern of +named, decimal, or hexadecimal character references are escaped. Invalid +named references (i.e. ambiguous ampersand) are are still permitted. + +**Related** + +- +- +- + +**Parameters** + +- **value** `string`: Original string. + +**Returns** + +`string` Escaped string. + +### escapeAttribute + +[src/index.js#L66-L68](src/index.js#L66-L68) + +Returns an escaped attribute value. + +**Related** + +- + +"[...] the text cannot contain an ambiguous ampersand [...] must not contain +any literal U+0022 QUOTATION MARK characters (")" + +**Parameters** + +- **value** `string`: Attribute value. + +**Returns** + +`string` Escaped attribute value. + +### escapeHTML + +[src/index.js#L82-L84](src/index.js#L82-L84) + +Returns an escaped HTML element value. + +**Related** + +- + +"the text must not contain the character U+003C LESS-THAN SIGN (\<) or an +ambiguous ampersand." + +**Parameters** + +- **value** `string`: Element value. + +**Returns** + +`string` Escaped HTML element value. + +### escapeLessThan + +[src/index.js#L50-L52](src/index.js#L50-L52) + +Returns a string with less-than sign replaced. + +**Parameters** + +- **value** `string`: Original string. + +**Returns** + +`string` Escaped string. + +### escapeQuotationMark + +[src/index.js#L39-L41](src/index.js#L39-L41) + +Returns a string with quotation marks replaced. + +**Parameters** + +- **value** `string`: Original string. + +**Returns** + +`string` Escaped string. + +### isValidAttributeName + +[src/index.js#L93-L95](src/index.js#L93-L95) + +Returns true if the given attribute name is valid, or false otherwise. + +**Parameters** + +- **name** `string`: Attribute name to test. + +**Returns** + +`boolean` Whether attribute is valid. + + + +

Code is Poetry.

diff --git a/packages/escape-html/package.json b/packages/escape-html/package.json index 909f2bd4ec1f3..efd7563bab138 100644 --- a/packages/escape-html/package.json +++ b/packages/escape-html/package.json @@ -22,7 +22,13 @@ "dependencies": { "@babel/runtime": "^7.3.1" }, + "devDependencies": { + "@wordpress/docgen": "file:../docgen" + }, "publishConfig": { "access": "public" + }, + "scripts": { + "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 47fff58a23250e69e76d0186ba2440fea43f6f7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 13:11:45 +0100 Subject: [PATCH 2/3] Use new script --- bin/update-readmes.js | 2 ++ packages/escape-html/README.md | 12 ++++++------ packages/escape-html/package.json | 6 ------ 3 files changed, 8 insertions(+), 12 deletions(-) diff --git a/bin/update-readmes.js b/bin/update-readmes.js index c4bd256f0a8ed..52b296114e181 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -6,6 +6,7 @@ const childProcess = require( 'child_process' ); const packages = [ 'e2e-test-utils', 'element', + 'escape-html', ]; let aggregatedExitCode = 0; @@ -14,6 +15,7 @@ packages.forEach( ( packageName ) => { `packages/${ packageName }/src/index.js`, `--output packages/${ packageName }/README.md`, '--to-token', + '--ignore "unstable|experimental"', ]; const pathToDocGen = path.join( __dirname, '..', 'node_modules', '.bin', 'docgen' ); const { status, stderr } = childProcess.spawnSync( diff --git a/packages/escape-html/README.md b/packages/escape-html/README.md index f5ceb1c685fc4..d144be1b7de9f 100644 --- a/packages/escape-html/README.md +++ b/packages/escape-html/README.md @@ -37,7 +37,7 @@ named references (i.e. ambiguous ampersand) are are still permitted. **Returns** -`string` Escaped string. +`string`: Escaped string. ### escapeAttribute @@ -58,7 +58,7 @@ any literal U+0022 QUOTATION MARK characters (")" **Returns** -`string` Escaped attribute value. +`string`: Escaped attribute value. ### escapeHTML @@ -79,7 +79,7 @@ ambiguous ampersand." **Returns** -`string` Escaped HTML element value. +`string`: Escaped HTML element value. ### escapeLessThan @@ -93,7 +93,7 @@ Returns a string with less-than sign replaced. **Returns** -`string` Escaped string. +`string`: Escaped string. ### escapeQuotationMark @@ -107,7 +107,7 @@ Returns a string with quotation marks replaced. **Returns** -`string` Escaped string. +`string`: Escaped string. ### isValidAttributeName @@ -121,7 +121,7 @@ Returns true if the given attribute name is valid, or false otherwise. **Returns** -`boolean` Whether attribute is valid. +`boolean`: Whether attribute is valid. diff --git a/packages/escape-html/package.json b/packages/escape-html/package.json index efd7563bab138..909f2bd4ec1f3 100644 --- a/packages/escape-html/package.json +++ b/packages/escape-html/package.json @@ -22,13 +22,7 @@ "dependencies": { "@babel/runtime": "^7.3.1" }, - "devDependencies": { - "@wordpress/docgen": "file:../docgen" - }, "publishConfig": { "access": "public" - }, - "scripts": { - "docs:generate": "docgen ./src/index.js --output ./README.md --to-token" } } From 1547e5d3d396d9732bd24e3333160079a50418ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s?= Date: Wed, 6 Mar 2019 18:24:24 +0100 Subject: [PATCH 3/3] Add all packages to be documented to the array The ones not ready are commented. This will avoid rebasing nightmares. --- bin/update-readmes.js | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/bin/update-readmes.js b/bin/update-readmes.js index 52b296114e181..ce9d702bbbba7 100755 --- a/bin/update-readmes.js +++ b/bin/update-readmes.js @@ -4,9 +4,34 @@ const path = require( 'path' ); const childProcess = require( 'child_process' ); const packages = [ + //'a11y', + //'autop', + //'blob', + //'block-editor', + //'block-library', + //'block-serialization-default-parser', + //'blocks', + //'compose', + //'data', + //'date', + //'deprecated', + //'dom', + //'dom-ready', 'e2e-test-utils', + //'edit-post', 'element', 'escape-html', + //'html-entities', + //'i18n', + //'keycodes', + //'plugins', + //'priority-queue', + //'redux-routine', + //'rich-text', + //'shortcode', + //'url', + //'viewport', + //'wordcount', ]; let aggregatedExitCode = 0;