From ec0706f123dc2e65db71a93ee9b836df8988c5ce Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s?= <nosolosw@users.noreply.github.com>
Date: Fri, 8 Mar 2019 07:44:18 +0100
Subject: [PATCH] shortcode: set up autogenerated API docs (#14218)

---
 bin/update-readmes.js        |   2 +-
 packages/shortcode/README.md | 147 +++++++++++++++++++++++++++++++++++
 2 files changed, 148 insertions(+), 1 deletion(-)

diff --git a/bin/update-readmes.js b/bin/update-readmes.js
index be50b22a6b0618..dafdf7d4743034 100755
--- a/bin/update-readmes.js
+++ b/bin/update-readmes.js
@@ -29,7 +29,7 @@ const packages = [
 	'priority-queue',
 	//'redux-routine',
 	'rich-text',
-	//'shortcode',
+	'shortcode',
 	//'url',
 	//'viewport',
 	//'wordcount',
diff --git a/packages/shortcode/README.md b/packages/shortcode/README.md
index 4887cf2fdcbf7b..4fc494b224206b 100644
--- a/packages/shortcode/README.md
+++ b/packages/shortcode/README.md
@@ -12,4 +12,151 @@ npm install @wordpress/shortcode --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) -->
+
+### attrs
+
+[src/index.js#L167-L210](src/index.js#L167-L210)
+
+Parse shortcode attributes.
+
+Shortcodes accept many types of attributes. These can chiefly be divided into
+named and numeric attributes:
+
+Named attributes are assigned on a key/value basis, while numeric attributes
+are treated as an array.
+
+Named attributes can be formatted as either `name="value"`, `name='value'`,
+or `name=value`. Numeric attributes can be formatted as `"value"` or just
+`value`.
+
+**Parameters**
+
+-   **text** `string`: Serialised shortcode attributes.
+
+**Returns**
+
+`WPShortcodeAttrs`: Parsed shortcode attributes.
+
+### default
+
+[src/index.js#L363-L363](src/index.js#L363-L363)
+
+Creates a shortcode instance.
+
+To access a raw representation of a shortcode, pass an `options` object,
+containing a `tag` string, a string or object of `attrs`, a string indicating
+the `type` of the shortcode ('single', 'self-closing', or 'closed'), and a
+`content` string.
+
+**Parameters**
+
+-   **options** `Object`: Options as described.
+
+**Returns**
+
+`WPShortcode`: Shortcode instance.
+
+### fromMatch
+
+[src/index.js#L223-L240](src/index.js#L223-L240)
+
+Generate a Shortcode Object from a RegExp match.
+
+Accepts a `match` object from calling `regexp.exec()` on a `RegExp` generated
+by `regexp()`. `match` can also be set to the `arguments` from a callback
+passed to `regexp.replace()`.
+
+**Parameters**
+
+-   **match** `Array`: Match array.
+
+**Returns**
+
+`WPShortcode`: Shortcode instance.
+
+### next
+
+[src/index.js#L45-L80](src/index.js#L45-L80)
+
+Find the next matching shortcode.
+
+**Parameters**
+
+-   **tag** `string`: Shortcode tag.
+-   **text** `string`: Text to search.
+-   **index** `number`: Index to start search from.
+
+**Returns**
+
+`?WPShortcodeMatch`: Matched information.
+
+### regexp
+
+[src/index.js#L146-L148](src/index.js#L146-L148)
+
+Generate a RegExp to identify a shortcode.
+
+The base regex is functionally equivalent to the one found in
+`get_shortcode_regex()` in `wp-includes/shortcodes.php`.
+
+Capture groups:
+
+1.  An extra `[` to allow for escaping shortcodes with double `[[]]`
+2.  The shortcode name
+3.  The shortcode argument list
+4.  The self closing `/`
+5.  The content of a shortcode when it wraps some content.
+6.  The closing tag.
+7.  An extra `]` to allow for escaping shortcodes with double `[[]]`
+
+**Parameters**
+
+-   **tag** `string`: Shortcode tag.
+
+**Returns**
+
+`RegExp`: Shortcode RegExp.
+
+### replace
+
+[src/index.js#L92-L107](src/index.js#L92-L107)
+
+Replace matching shortcodes in a block of text.
+
+**Parameters**
+
+-   **tag** `string`: Shortcode tag.
+-   **text** `string`: Text to search.
+-   **callback** `Function`: Function to process the match and return replacement string.
+
+**Returns**
+
+`string`: Text with shortcodes replaced.
+
+### string
+
+[src/index.js#L122-L124](src/index.js#L122-L124)
+
+Generate a string from shortcode parameters.
+
+Creates a shortcode instance and returns a string.
+
+Accepts the same `options` as the `shortcode()` constructor, containing a
+`tag` string, a string or object of `attrs`, a boolean indicating whether to
+format the shortcode using a `single` tag, and a `content` string.
+
+**Parameters**
+
+-   **options** `Object`: 
+
+**Returns**
+
+`string`: String representation of the shortcode.
+
+
+<!-- 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>