Refactor readme.md

readme.md

@@ -1,104 +1,141 @@
-# unist-util-map [![Build Status][build-badge]][build-page]
+# unist-util-map
 
-Create a new Unist tree with all nodes that mapped by the provided function.
+[![Build][build-badge]][build]
+[![Coverage][coverage-badge]][coverage]
+[![Downloads][downloads-badge]][downloads]
+[![Size][size-badge]][size]
 
-Helper for creating [unist: Universal Syntax Tree][unist].
+[**unist**][unist] utility to create a new [tree][] by mapping all [node][]s
+with the given function.
 
-*   [retext][], [remark][], [rehype][], [textlint][]
+## Install
 
-## Installation
+[npm][]:
 
 ```sh
 npm install unist-util-map
 ```
 
 ## Usage
 
-### `map(AST, function(node, index, parent){ /* return */ }): AST`
+```js
+var u = require('unist-builder')
+var map = require('unist-util-map')
+
+var tree = u('tree', [
+  u('leaf', 'leaf 1'),
+  u('node', [u('leaf', 'leaf 2')]),
+  u('void'),
+  u('leaf', 'leaf 3')
+])
+
+var next = map(tree, function(node) {
+  return node.type === 'leaf'
+    ? Object.assign({}, node, {value: 'CHANGED'})
+    : node
+})
 
-map function return new AST object.
+console.dir(next, {depth: null})
+```
 
-```js
-const assert = require('assert')
-const assign = require('object-assign')
-const map = require('unist-util-map')
+Yields:
 
-// Input
-const tree = {
-  type: 'root',
+```js
+{
+  type: 'tree',
   children: [
-    {
-      type: 'node',
-      children: [{type: 'leaf', value: '1'}]
-    },
-    {type: 'leaf', value: '2'}
+    { type: 'leaf', value: 'CHANGED' },
+    { type: 'node', children: [ { type: 'leaf', value: 'CHANGED' } ] },
+    { type: 'void' },
+    { type: 'leaf', value: 'CHANGED' }
   ]
 }
+```
 
-// Transform:
-const actual = map(tree, function(node) {
-  if (node.type === 'leaf') {
-    return assign({}, node, {value: 'CHANGED'})
-  }
-  // No change
-  return node
-})
+…note that `tree` is not mutated.
 
-// Expected output:
-const expected = {
-  type: 'root',
-  children: [
-    {
-      type: 'node',
-      children: [{type: 'leaf', value: 'CHANGED'}]
-    },
-    {type: 'leaf', value: 'CHANGED'}
-  ]
-}
+## API
 
-assert.deepEqual(actual, expected)
-```
+### `map(tree, mapFn)`
 
-## Tests
+Create a new [tree][] by mapping all [node][]s with the given function.
 
-```sh
-npm test
-```
+###### Parameters
+
+*   `tree` ([`Node`][node]) — [Tree][] to map
+*   `callback` ([`Function`][callback]) — Function that returns a new node
+
+###### Returns
+
+[`Node`][node] — New mapped [tree][].
 
-## Contributing
+#### `function mapFn(node[, index, parent])`
 
-1.  Fork it!
-2.  Create your feature branch: `git checkout -b my-new-feature`
-3.  Commit your changes: `git commit -am 'Add some feature'`
-4.  Push to the branch: `git push origin my-new-feature`
-5.  Submit a pull request :D
+Function called with a [node][] to produce a new node.
 
-See [`contribute.md` in `syntax-tree/unist`][contributing] for ways to get
+###### Parameters
+
+*   `node` ([`Node`][node]) — Current [node][] being processed
+*   `index` (`number?`) — [Index][] of `node`, or `null`
+*   `parent` (`Node?`) — [Parent][] of `node`, or `null`
+
+###### Returns
+
+[`Node`][node] — Node to be used in the new [tree][].
+Its children are not used: if the original node has children, those are mapped.
+
+## Contribute
+
+See [`contributing.md` in `syntax-tree/.github`][contributing] for ways to get
 started.
+See [`support.md`][support] for ways to get help.
 
-This organisation has a [Code of Conduct][coc].  By interacting with this
-repository, organisation, or community you agree to abide by its terms.
+This project has a [Code of Conduct][coc].
+By interacting with this repository, organisation, or community you agree to
+abide by its terms.
 
 ## License
 
-[MIT][]
+[MIT][license] © [azu][author]
+
+<!-- Definitions -->
+
+[build-badge]: https://img.shields.io/travis/syntax-tree/unist-util-find-all-after.svg
+
+[build]: https://travis-ci.org/syntax-tree/unist-util-find-all-after
+
+[coverage-badge]: https://img.shields.io/codecov/c/github/syntax-tree/unist-util-find-all-after.svg
+
+[coverage]: https://codecov.io/github/syntax-tree/unist-util-find-all-after
+
+[downloads-badge]: https://img.shields.io/npm/dm/unist-util-find-all-after.svg
+
+[downloads]: https://www.npmjs.com/package/unist-util-find-all-after
+
+[size-badge]: https://img.shields.io/bundlephobia/minzip/unist-util-find-all-after.svg
+
+[size]: https://bundlephobia.com/result?p=unist-util-find-all-after
+
+[npm]: https://docs.npmjs.com/cli/install
+
+[license]: license
 
-[build-badge]: https://img.shields.io/travis/syntax-tree/unist-util-map.svg
+[author]: https://efcl.info
 
-[build-page]: https://travis-ci.org/syntax-tree/unist-util-map
+[unist]: https://github.com/syntax-tree/unist
 
-[unist]: https://github.com/wooorm/unist "wooorm/unist: Universal Syntax Tree"
+[node]: https://github.com/syntax-tree/unist#node
 
-[contributing]: https://github.com/syntax-tree/unist/blob/master/contributing.md
+[tree]: https://github.com/syntax-tree/unist#tree
 
-[coc]: https://github.com/syntax-tree/unist/blob/master/code-of-conduct.md
+[parent]: https://github.com/syntax-tree/unist#parent-1
 
-[remark]: https://github.com/remarkjs/remark
+[index]: https://github.com/syntax-tree/unist#index
 
-[retext]: https://github.com/retextjs/retext
+[callback]: #function-mapfnnode-index-parent
 
-[rehype]: https://github.com/rehypejs/rehype
+[contributing]: https://github.com/syntax-tree/.github/blob/master/contributing.md
 
-[textlint]: https://github.com/textlint/textlint
+[support]: https://github.com/syntax-tree/.github/blob/master/support.md
 
-[mit]: license
+[coc]: https://github.com/syntax-tree/.github/blob/master/code-of-conduct.md