From ff736745d6ad414679f3496a60ef1873502f87c0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Fri, 1 Mar 2019 20:10:52 +0100
Subject: [PATCH 1/3] Autogenerated docs and setup for html-entities

---
 packages/html-entities/README.md    | 13 +++++++++++++
 packages/html-entities/package.json |  6 ++++++
 2 files changed, 19 insertions(+)

diff --git a/packages/html-entities/README.md b/packages/html-entities/README.md
index f86def2a5dcc9..20af18f032176 100644
--- a/packages/html-entities/README.md
+++ b/packages/html-entities/README.md
@@ -12,4 +12,17 @@ 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#L3-L22](src/index.js#L3-L22)
+
+Undocumented declaration.
+
+
+<!-- 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/package.json b/packages/html-entities/package.json
index 6b6d7ec47910d..f378df1b6129b 100644
--- a/packages/html-entities/package.json
+++ b/packages/html-entities/package.json
@@ -24,7 +24,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 fd32135f95cefdc510bc7ca2bc69b824e6ffc5fd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Mar 2019 12:47:03 +0100
Subject: [PATCH 2/3] Use new script

---
 bin/update-readmes.js               | 2 +-
 packages/html-entities/package.json | 6 ------
 2 files changed, 1 insertion(+), 7 deletions(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index ce9d702bbbba7..038cfa34c6213 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/package.json b/packages/html-entities/package.json
index f378df1b6129b..6b6d7ec47910d 100644
--- a/packages/html-entities/package.json
+++ b/packages/html-entities/package.json
@@ -24,13 +24,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 830d9ca89cf9ae7e19b1972b86ee5ca077d323c8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <andres.maneiro@automattic.com>
Date: Wed, 6 Mar 2019 12:55:48 +0100
Subject: [PATCH 3/3] Update docs

---
 packages/html-entities/README.md    | 19 +++++++++++++++++--
 packages/html-entities/src/index.js | 13 +++++++++++++
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/packages/html-entities/README.md b/packages/html-entities/README.md
index 20af18f032176..2d13431fa13b4 100644
--- a/packages/html-entities/README.md
+++ b/packages/html-entities/README.md
@@ -18,9 +18,24 @@ _This package assumes that your code will run in an **ES2015+** environment. If
 
 ### decodeEntities
 
-[src/index.js#L3-L22](src/index.js#L3-L22)
+[src/index.js#L16-L35](src/index.js#L16-L35)
 
-Undocumented declaration.
+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) -->
diff --git a/packages/html-entities/src/index.js b/packages/html-entities/src/index.js
index 7fe93882223c5..15c04fe51268a 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( '&' ) ) {