From 1bcee0b69bf39f12c28eeb1b7f3f09558a83d882 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <nosolosw@users.noreply.github.com>
Date: Wed, 6 Mar 2019 18:46:02 +0100
Subject: [PATCH] escape-html: set up autogenerated API docs (#14268)

---
 bin/update-readmes.js          |  27 ++++++++
 packages/escape-html/README.md | 114 +++++++++++++++++++++++++++++++++
 2 files changed, 141 insertions(+)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index c4bd256f0a8edf..ce9d702bbbba77 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -4,8 +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;
@@ -14,6 +40,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 310034d07cd8e1..d144be1b7de9f6 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
+
+<!-- START TOKEN(Autogenerated API docs) -->
+
+### 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**
+
+-   <https://w3c.github.io/html/syntax.html#character-references>
+-   <https://w3c.github.io/html/syntax.html#ambiguous-ampersand>
+-   <https://w3c.github.io/html/syntax.html#named-character-references>
+
+**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**
+
+-   <https://w3c.github.io/html/syntax.html#elements-attributes>
+
+"[...] 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**
+
+-   <https://w3c.github.io/html/syntax.html#writing-html-documents-elements>
+
+"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.
+
+
+<!-- END TOKEN(Autogenerated API docs) -->
+
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>