readme <3

README.md

@@ -10,153 +10,170 @@ IPFS Blocks JavaScript Implementation
 [![Dependency Status](https://david-dm.org/ipfs/js-ipfs-blocks.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfs-blocks)
 [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
 
-> JavaScript Implementation of the BlockService and Block data structure
+> [IPFS][ipfs] implementation of the BlockService and Block data structure in
+> JavaScript.
 
-## Architecture
+## Description
+
+**Block** - A block is a blob of binary data.
+
+**BlockService** - A BlockService is a content-addressable store for blocks,
+providing an API for adding, deleting, and retrieving blocks. A BlockService is
+backed by an [IPFS Repo][repo] as its datastore for blocks, and uses an [IPFS
+Exchange][bitswap] implementation to fetch blocks from the network.
 
 ```markdown
 ┌────────────────────┐
-│   BlockService     │
+│     BlockService   │
 └────────────────────┘
            │
      ┌─────┴─────┐
      ▼           ▼
 ┌─────────┐ ┌────────┐
-│IPFS REPO│ │Exchange│
+│IPFS Repo│ │Exchange│
 └─────────┘ └────────┘
 ```
 
-**BlockService** - The BlockService uses IPFS Repo as the local datastore for blocks and an IPFS Exchange compliant implementation to fetch blocks from the network.
+## Example
+
+```js
+const blocks = require('ipfs-blocks')
+const IPFSRepo = require('ipfs-repo')  // storage repo
+const memstore = require('abstract-blob-store')  // in-memory store
+
+// setup a repo
+var repo = new IPFSRepo('example', { stores: memstore })
+
+// create a block
+const block = new blocks.Block('hello warld')
+console.log(block.data)
+console.log(block.key)
+
+// create a service
+const bs = new blocks.BlockService(repo)
 
-A Block is a data structure available on this module.
+// add the block, then retrieve it
+bs.addBlock(block, function (err) {
+  bs.getBlock(block.key, function (err, b) {
+    console.log(block.data.toString() === b.data.toString())
+  })
+})
+```
+
+outputs
 
-# Installation
+```
+<Buffer 68 65 6c 6c 6f 20 77 61 72 6c 64>
 
-## npm
+<Buffer 12 20 db 3c 15 23 3f f3 84 8f 42 fe 3b 74 78 90 90 5a 80 7e a6 ef 2b 6d 2f 3c 8b 2c b7 ae be 86 3c 4d>
+
+true
+
+```
+
+## Installation
+
+### npm
 
 ```sh
 > npm i ipfs-blocks
 ```
 
-## Use in Node.js
+## Setup
+
+### Node.js
 
 ```js
-const ipfsBlocks = require('ipfs-blocks')
+const blocks = require('ipfs-blocks')
 ```
 
-## Use in a browser with browserify, webpack or any other bundler
+### Browser: Browserify, Webpack, other bundlers
 
-The code published to npm that gets loaded on require is in fact a ES5 transpiled version with the right shims added. This means that you can require it and use with your favourite bundler without having to adjust asset management process.
+The code published to npm that gets loaded on require is in fact a ES5
+transpiled version with the right shims added. This means that you can require
+it and use with your favourite bundler without having to adjust asset management
+process.
 
 ```JavaScript
-var ipfsBlocks = require('ipfs-blocks')
+var blocks = require('ipfs-blocks')
 ```
 
-## Use in a browser Using a script tag
+### Browser: `<script>` Tag
 
-Loading this module through a script tag will make the `Unixfs` obj available in the global namespace.
+Loading this module through a script tag will make the `Unixfs` obj available in
+the global namespace.
 
 ```html
 <script src="https://npmcdn.com/ipfs-blocks/dist/index.min.js"></script>
 <!-- OR -->
 <script src="https://npmcdn.com/ipfs-blocks/dist/index.js"></script>
 ```
 
-# Usage
-
+## API
 
 ```js
-// then, to access each of the components
-ipfsBlocks.BlockService
-ipfsBlocks.Block
+const blocks = require('ipfs-blocks')
 ```
 
-#### Block
+### Block
 
-Create a new block
+#### var block = new blocks.Block(data)
 
-```js
-const block = new blocks.Block('some data')
-console.log(block.data)
-// It will print 'some data'
+Creates a new block with raw data `data`.
 
-console.log(block.key)
-// It will print the sha256 multihash of 'some data'
-```
+#### block.data
 
-A block can also have it's own extension, which by default is `data`.
+The raw data of the block. Its format matches whatever was provided in its
+constructor.
 
-```js
-const block = new blocks.Block('data', 'ipld')
-console.log(block.extension)
-// => ipld
-```
+#### block.key
 
-#### BlockService
+The [multihash][multihash] of the block's data, as a buffer.
 
-Create a new block service
+### var bs = new blocks.BlockService(repo[, exchange])
 
-```js
-const bs = new ipfsBlocks.BlockService(<IPFS REPO instance> [, <IPFS Exchange>])
-```
+Creates a new block service backed by [IPFS Repo][repo] `repo` for storage, and
+[IPFS Exchange][bitswap] for retrieving blocks from the network. Providing an
+`exchange` is optional.
 
-##### `addBlock`
+#### bs.addBlock(block, callback(err))
 
-```js
-bs.addBlock(block, function (err) {
-  if (!err) {
-    // block successfuly added
-  }
-})
-```
+Asynchronously adds a block instance to the underlying repo.
 
-##### `addBlocks`
+#### bs.addBlocks(blocks, callback(err))
 
-```js
-bs.addBlocks(blockArray, function (err) {
-  if (!err) {
-    // blocks successfuly added
-  }
-})
-```
+Asynchronously adds an array of block instances to the underlying repo.
 
-##### `getBlock`
+*Does not guarantee atomicity.*
 
-```js
-bs.getBlock(multihash, function (err, block) {
-  if (!err) {
-    // block successfuly retrieved
-  }
-})
-```
+#### bs.getBlock(multihash, callback(err, block))
 
+Asynchronously returns the block whose content multihash matches `multihash`.
 
-##### `getBlocks`
+#### bs.getBlocks(multihashes, callback(err, blocks))
 
-```js
-bs.getBlocks(multihashArray, function (err, block) {
-  if (!err) {
-    // block successfuly retrieved
-  }
-})
-```
+Asynchronously returns the blocks whose content multihashes match the array
+`multihashes`.
 
-##### `deleteBlock`
+*Does not guarantee atomicity.*
 
-```js
-bs.deleteBlock(multihash, function (err) {
-  if (!err) {
-    // block successfuly deleted
-  }
-})
-```
+#### bs.deleteBlock(multihash, callback(err))
 
-##### `deleteBlocks`
+Asynchronously deletes the block from the store with content multihash matching
+`multihash`, if it exists.
 
-```js
-bs.deleteBlocks(multihashArray, function (err) {
-  if (!err) {
-    // blocks successfuly deleted
-  }
-})
-```
+#### bs.deleteBlocks(multihashes, callback(err))
+
+Asynchronously deletes all blocks from the store with content multihashes matching
+from the array `multihashes`.
+
+*Does not guarantee atomicity.*
+
+## License
+
+MIT
+
+[ipfs]: https://ipfs.io
+[repo]: https://github.com/ipfs/specs/tree/master/repo
+[bitswap]: https://github.com/ipfs/specs/tree/master/bitswap
+[multihash]: https://github.com/jbenet/js-multihash