From 032d96e2b077095b941ef8d9e6ad727dfa72f67b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <nosolosw@users.noreply.github.com>
Date: Thu, 7 Mar 2019 09:35:40 +0100
Subject: [PATCH] autop: set up auto-generated API docs (#14287)

---
 bin/update-readmes.js       |  2 +-
 packages/autop/README.md    | 58 ++++++++++++++++++++++++++++++-------
 packages/autop/src/index.js | 14 +++++++++
 3 files changed, 63 insertions(+), 11 deletions(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index 98c831386475d9..da84d066eef751 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -5,7 +5,7 @@ const childProcess = require( 'child_process' );
 
 const packages = [
 	'a11y',
-	//'autop',
+	'autop',
 	'blob',
 	//'block-editor',
 	'block-library',
diff --git a/packages/autop/README.md b/packages/autop/README.md
index 4aecd9cafa3de3..ffb9168b63f208 100644
--- a/packages/autop/README.md
+++ b/packages/autop/README.md
@@ -12,23 +12,61 @@ npm install @wordpress/autop --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)._
 
-### Usage
+### API
 
-Import the desired function(s) from `@wordpress/autop`:
+<!-- START TOKEN(Autogenerated API docs) -->
+
+#### autop
+
+[src/index.js#L129-L285](src/index.js#L129-L285)
+
+Replaces double line-breaks with paragraph elements.
+
+A group of regex replaces used to identify text formatted with newlines and
+replace double line-breaks with HTML paragraph tags. The remaining line-
+breaks after conversion become `<br />` tags, unless br is set to 'false'.
+
+**Usage**
 
 ```js
-import { autop, removep } from '@wordpress/autop';
+import { autop } from '@wordpress/autop';
+autop( 'my text' ); // "<p>my text</p>"
+```
+
+**Parameters**
+
+-   **text** `string`: The text which has to be formatted.
+-   **br** `boolean`: Optional. If set, will convert all remaining line- breaks after paragraphing. Default true.
+
+**Returns**
+
+`string`: Text which has been converted into paragraph tags.
 
-autop( 'my text' );
-// "<p>my text</p>"
+#### removep
 
-removep( '<p>my text</p>' );
-// "my text"
+[src/index.js#L303-L426](src/index.js#L303-L426)
+
+Replaces `<p>` tags with two line breaks. "Opposite" of autop().
+
+Replaces `<p>` tags with two line breaks except where the `<p>` has attributes.
+Unifies whitespace. Indents `<li>`, `<dt>` and `<dd>` for better readability.
+
+**Usage**
+
+```js
+import { removep } from '@wordpress/autop';
+removep( '<p>my text</p>' ); // "my text"
 ```
 
-### API Usage
+**Parameters**
+
+-   **html** `string`: The content from the editor.
+
+**Returns**
+
+`string`: The content with stripped paragraph tags.
+
 
-* `autop( text: string ): string`
-* `removep( text: string ): 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/autop/src/index.js b/packages/autop/src/index.js
index 916f56a4be5f21..809a66b412d698 100644
--- a/packages/autop/src/index.js
+++ b/packages/autop/src/index.js
@@ -117,6 +117,13 @@ function replaceInHtmlTags( haystack, replacePairs ) {
  * @param  {string}    text The text which has to be formatted.
  * @param  {boolean}   br   Optional. If set, will convert all remaining line-
  *                          breaks after paragraphing. Default true.
+ *
+ * @example
+ *```js
+ * import { autop } from '@wordpress/autop';
+ * autop( 'my text' ); // "<p>my text</p>"
+ * ```
+ *
  * @return {string}         Text which has been converted into paragraph tags.
  */
 export function autop( text, br = true ) {
@@ -284,6 +291,13 @@ export function autop( text, br = true ) {
  * Unifies whitespace. Indents `<li>`, `<dt>` and `<dd>` for better readability.
  *
  * @param  {string} html The content from the editor.
+ *
+ * @example
+ * ```js
+ * import { removep } from '@wordpress/autop';
+ * removep( '<p>my text</p>' ); // "my text"
+ * ```
+ *
  * @return {string}      The content with stripped paragraph tags.
  */
 export function removep( html ) {