From 7d986580b463f927c62f65209f850a61c54bc8bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <nosolosw@users.noreply.github.com>
Date: Wed, 6 Mar 2019 19:04:42 +0100
Subject: [PATCH] html-entities: set up auto-generated API docs (#14267)

---
 bin/update-readmes.js               |  2 +-
 packages/html-entities/README.md    | 28 ++++++++++++++++++++++++++++
 packages/html-entities/src/index.js | 13 +++++++++++++
 3 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index ce9d702bbbba77..038cfa34c62133 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -21,7 +21,7 @@ const packages = [
 	//'edit-post',
 	'element',
 	'escape-html',
-	//'html-entities',
+	'html-entities',
 	//'i18n',
 	//'keycodes',
 	//'plugins',
diff --git a/packages/html-entities/README.md b/packages/html-entities/README.md
index f86def2a5dcc90..2d13431fa13b4d 100644
--- a/packages/html-entities/README.md
+++ b/packages/html-entities/README.md
@@ -12,4 +12,32 @@ npm install @wordpress/html-entities --save
 
 _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) -->
+
+### decodeEntities
+
+[src/index.js#L16-L35](src/index.js#L16-L35)
+
+Decodes the HTML entities from a given string.
+
+**Usage**
+
+```js
+const result = decodeEntities( '&aacute;' );
+console.log( result ); // result will be "á"
+```
+
+**Parameters**
+
+-   **html** `string`: String that contain HTML entities.
+
+**Returns**
+
+`string`: The decoded string.
+
+
+<!-- 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>
diff --git a/packages/html-entities/src/index.js b/packages/html-entities/src/index.js
index 7fe93882223c56..15c04fe51268ad 100644
--- a/packages/html-entities/src/index.js
+++ b/packages/html-entities/src/index.js
@@ -1,5 +1,18 @@
 let _decodeTextArea;
 
+/**
+ * Decodes the HTML entities from a given string.
+ *
+ * @param {string} html String that contain HTML entities.
+ *
+ * @example
+ * ```js
+ * const result = decodeEntities( '&aacute;' );
+ * console.log( result ); // result will be "á"
+ * ```
+ *
+ * @return {string} The decoded string.
+ */
 export function decodeEntities( html ) {
 	// not a string, or no entities to decode
 	if ( 'string' !== typeof html || -1 === html.indexOf( '&' ) ) {