Refactor docs

Author: wooorm

readme.md

@@ -1,109 +1,89 @@
-# unist-util-modify-children [![Build Status](https://img.shields.io/travis/wooorm/unist-util-modify-children.svg)](https://travis-ci.org/wooorm/unist-util-modify-children) [![Coverage Status](https://img.shields.io/codecov/c/github/wooorm/unist-util-modify-children.svg)](https://codecov.io/github/wooorm/unist-util-modify-children)
+# unist-util-modify-children [![Build Status][travis-badge]][travis] [![Coverage Status][codecov-badge]][codecov]
 
-[Unist](https://github.com/wooorm/unist) ([mdast](https://github.com/wooorm/mdast/blob/master/doc/mdastnode.7.md),
-[retext](https://github.com/wooorm/retext)) utility to modify direct children of
-a parent. As in, wrap `fn` so it accepts a parent and invoke `fn` for each of
-its children. When `fn` returns a number, goes to that child next.
+Modify direct children of a parent.
 
 ## Installation
 
-[npm](https://docs.npmjs.com/cli/install):
+[npm][]:
 
 ```bash
 npm install unist-util-modify-children
 ```
 
-**unist-util-modify-children** is also available for [bower](http://bower.io/#install-packages),
-[component](https://github.com/componentjs/component), and
-[duo](http://duojs.org/#getting-started), and as an AMD, CommonJS, and globals
-module, [uncompressed](unist-util-modify-children.js) and [compressed](unist-util-modify-children.min.js).
-
 ## Usage
 
-```js
+```javascript
+var remark = require('remark');
 var modifyChildren = require('unist-util-modify-children');
 
-var modifier = modifyChildren(function (child, index, parent) {
-    console.log(child, index);
-
-    if (child.value === 'bravo') {
-        parent.children.splice(index + 1, 0, { 'type': 'bar', 'value': 'delta' });
-        return index + 1;
-    }
-});
-
-var parent = {
-    'type': 'foo',
-    'children': [
-        { 'type': 'bar', 'value': 'alpha' },
-        { 'type': 'bar', 'value': 'bravo' },
-        { 'type': 'bar', 'value': 'charlie' }
-    ]
-};
-
-modifier(parent);
-/*
- * { type: 'bar', value: 'alpha' } 0
- * { type: 'bar', value: 'bravo' } 1
- * { type: 'bar', value: 'delta' } 2
- * { type: 'bar', value: 'charlie' } 3
- */
-
-console.log(parent);
-/*
- * { type: 'foo',
- *   children:
- *    [ { type: 'bar', value: 'alpha' },
- *      { type: 'bar', value: 'bravo' },
- *      { type: 'bar', value: 'delta' },
- *      { type: 'bar', value: 'charlie' } ] }
- */
+var doc = remark().use(plugin).process('This _and_ that');
+
+console.log(String(doc));
+
+function plugin() {
+  return transformer;
+  function transformer(tree) {
+    modifyChildren(modifier)(tree.children[0]);
+  }
+}
+
+function modifier(node, index, parent) {
+  if (node.type === 'emphasis') {
+    parent.children.splice(index, 1, {type: 'strong', children: node.children});
+    return index + 1;
+  }
+}
+```
+
+Yields:
+
+```js
+This **and** that
 ```
 
 ## API
 
-### modifyChildren(fn)
+### `modify = modifyChildren(modifier)`
 
-**Parameters**
+Wrap [`modifier`][modifier] to be invoked for each child in the node given to
+[`modify`][modify].
 
-*   `fn` ([`Function`](#function-fnchild-index-parent))
-    — Function to wrap.
+#### `next? = modifier(child, index, parent)`
 
-**Return**
+Invoked if [`modify`][modify] is called on a parent node for each `child`
+in `parent`.
 
-[`Function`](#function-pluginparent) — Wrapped `fn`.
+###### Returns
 
-#### function fn(child, index, parent)
+`number` (optional) — Next position to iterate.
 
-Modifier for children of `parent`.
+#### `function modify(parent)`
 
-**Parameters**
+Invoke the bound [`modifier`][modifier] for each child in `parent`
+([`Node`][node]).
 
-*   `child` ([`Node`](https://github.com/wooorm/unist##unist-nodes))
-    — Current iteration;
+## License
 
-*   `index` (`number`) — Position of `child` in `parent`;
+[MIT][license] © [Titus Wormer][author]
 
-*   `parent` ([`Node`](https://github.com/wooorm/unist##unist-nodes))
-    — Parent node of `child`.
+<!-- Definitions -->
 
-**Returns**
+[travis-badge]: https://img.shields.io/travis/wooorm/unist-util-modify-children.svg
 
-`number` (optional) — Next position to iterate.
+[travis]: https://travis-ci.org/wooorm/unist-util-modify-children
 
-#### function plugin(parent)
+[codecov-badge]: https://img.shields.io/codecov/c/github/wooorm/unist-util-modify-children.svg
 
-Function invoking `fn` for each child of `parent`.
+[codecov]: https://codecov.io/github/wooorm/unist-util-modify-children
 
-**Parameters**
+[npm]: https://docs.npmjs.com/cli/install
 
-*   `parent` ([`Node`](https://github.com/wooorm/unist##unist-nodes))
-    — Node with children.
+[license]: LICENSE
 
-**Throws**
+[author]: http://wooorm.com
 
-*   `Error` — When not given a parent node.
+[node]: https://github.com/wooorm/unist#node
 
-## License
+[modifier]: #next--modifierchild-index-parent
 
-[MIT](LICENSE) © [Titus Wormer](http://wooorm.com)
+[modify]: #function-modifyparent