html-entities: set up auto-generated API docs (#14267)

bin/update-readmes.js

@@ -21,7 +21,7 @@ const packages = [
 	//'edit-post',
 	'element',
 	'escape-html',
-	//'html-entities',
+	'html-entities',
 	//'i18n',
 	//'keycodes',
 	//'plugins',

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>

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( 'á' );
+ * 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( '&' ) ) {