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] 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 20af18f032176b..2d13431fa13b4d 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 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( '&' ) ) {