Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

shortcode: set up autogenerated API docs #14218

Merged
merged 7 commits into from
Mar 8, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion bin/update-readmes.js
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ const packages = [
//'priority-queue',
//'redux-routine',
'rich-text',
//'shortcode',
'shortcode',
//'url',
//'viewport',
//'wordcount',
Expand Down
147 changes: 147 additions & 0 deletions packages/shortcode/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>