docs: review the readme (#181)

daviddias · web-flow · commit dbe6b371bc42 · 2018-01-09T17:00:51.000Z
* docs: review the readme

* Update README.md

* doc: updated `init()` docs
diff --git a/README.md b/README.md
@@ -10,7 +10,7 @@
 [![Appveyor CI](https://ci.appveyor.com/api/projects/status/4p9r12ch0jtthnha?svg=true)](https://ci.appveyor.com/project/wubalubadubdub/js-ipfsd-ctl-a9ywu)
 [![Dependency Status](https://david-dm.org/ipfs/js-ipfsd-ctl.svg?style=flat-square)](https://david-dm.org/ipfs/js-ipfsd-ctl) [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat-square)](https://github.com/feross/standard)
 
-> Control an ipfs node daemon using either Node.js or the browser
+> Control an IPFS daemon using JavaScript in Node.js or in the Browser.
 
 ```
                                                                     +-----+                                   
@@ -51,7 +51,7 @@ npm install --save ipfsd-ctl
 
 IPFS daemons are already easy to start and stop, but this module is here to do it from JavaScript itself.
 
-### Local daemon (_Spawn from from Node.js_)
+### Spawn an IPFS daemon from Node.js
 
 ```js
 // Start a disposable node, and get access to the api
@@ -61,14 +61,18 @@ const DaemonFactory = require('ipfsd-ctl')
 const df = DaemonFactory.create()
 
 df.spawn(function (err, ipfsd) {
+  if (err) { throw err }
+  
   ipfsd.api.id(function (err, id) {
+    if (err) { throw err }
+    
     console.log(id)
     ipfsd.stop()
   })
 })
 ```
 
-### Remote node _(Spawn from a Browser or from a remote machine))
+### Spawn an IPFS daemon from the Browser using the provided remote endpoint
 
 ```js
 // Start a remote disposable node, and get access to the api
@@ -78,18 +82,17 @@ const DaemonFactory = require('ipfsd-ctl')
 
 const port = 9999
 const server = DaemonFactory.createServer(port)
-const df = DaemonFactory.create({ remote: true, port })
+const df = DaemonFactory.create({ remote: true, port: port })
+
 server.start((err) => {
-  if (err) {
-    throw err
-  }
+  if (err) { throw err }
 
   df.spawn((err, ipfsd) => {
-    if (err) {
-      throw err
-    }
+    if (err) { throw err }
 
     ipfsd.api.id(function (err, id) {
+      if (err) { throw err }
+      
       console.log(id)
       ipfsd.stop(server.stop)
     })
@@ -110,174 +113,148 @@ server.start((err) => {
 
 ## API
 
-### Daemon Factory
+### Daemon Factory Class
 
-#### Create a `DaemonFactory` - `const df = DaemonFactory.create([options])`
+#### `DaemonFactory` - `const df = DaemonFactory.create([options])`
 
-> `DaemonFactory.create([options])` returns an object that will expose the `df.spawn` method
+`DaemonFactory.create([options])` returns an object that will expose the `df.spawn` method
 
 - `options` - an optional object with the following properties
   - `remote` bool - indicates if the factory should spawn local or remote nodes. By default, local nodes are spawned in Node.js and remote nodes are spawned in Browser environments.
   - `port` number - the port number to use for the remote factory. It should match the port on which `DaemonFactory.server` was started. Defaults to 9999.
-  - type - the daemon type to create with this factory. See the section bellow for the supported types
+  - `type` - the daemon type to create with this factory. See the section bellow for the supported types
+  - `exec` - path to the desired IPFS executable to spawn, otherwise `ipfsd-ctl` will try to locate the correct one based on the `type`. In the case of `proc` type, exec is required and expects an IPFS coderef.
   
-##### IPFS executable types
-
-`ipfsd-ctl` allows spawning different types of executables, such as:
-
-> `go`
-
-Invoking `df.create({type: 'go'})` will spawn a `go-ipfs` node.
-
-> `js`
-
-Invoking `df.create({type: 'js'})` will spawn a `js-ipfs` node.
-
-> `proc`
-
-Invoking `df.create({type: 'proc'})` will spawn an `in-process-ipfs` node using the provided code reference that implements the core IPFS API. Note that, `exec` option to `df.spawn()` is required if `type: 'proc'` is used.
+`ipfsd-ctl` allows spawning different IPFS implementations, such as:
 
+- **`go`** - calling `DaemonFactory.create({type: 'go'})` will spawn a `go-ipfs` daemon.
+- **`js`** - calling `DaemonFactory.create({type: 'js'})` will spawn a `js-ipfs` daemon.
+- **`proc`** - calling `DaemonFactory.create({type: 'proc', exec: require('ipfs') })` will spawn an `in process js-ipfs node` using the provided code reference that implements the core IPFS API. Note that, `exec` option to `df.spawn()` is required if `type: 'proc'` is used.
   
+#### DaemonFactory endpoint for remote spawning - `const server = DaemonFactory.createServer([options]) `
 
-#### Create a DaemonFactory Endpoint - `const server = DaemonFactory.createServer([options]) `
-
-> `DaemonFactory.createServer` create an instance of the bundled REST API used by the remote controller.
+`DaemonFactory.createServer` create an instance of the bundled REST API used by the remote controller.
 
-- exposes `start` and `stop` methods to start and stop the http server.
+- exposes `start` and `stop` methods to start and stop the http server endpoint.
 
 #### Spawn a new daemon with `df.spawn`
 
-> Spawn either a js-ipfs or go-ipfs node
+Spawn either a js-ipfs or go-ipfs daemon
 
-`spawn([options], callback)`
+`df.spawn([options], callback)`
 
-- `options` - is an optional object the following properties
+`options` is an optional object the following properties:
   - `init` bool (default true) - should the node be initialized
   - `start` bool (default true) - should the node be started
   - `repoPath` string - the repository path to use for this node, ignored if node is disposable
   - `disposable` bool (default false) - a new repo is created and initialized for each invocation, as well as cleaned up automatically once the process exits
   - `args` - array of cmd line arguments to be passed to ipfs daemon
   - `config` - ipfs configuration options
-  - `exec` - path to the desired IPFS executable to spawn, otherwise `ipfsd-ctl` will try to locate the correct one based on the `type`. In the case of `proc` type, exec is required and expects an IPFS coderef
-  
- - `callback` - is a function with the signature `cb(err, ipfsd)` where:
-   - `err` - is the error set if spawning the node is unsuccessful
-   - `ipfsd` - is the daemon controller instance: 
-     - `api` - a property of `ipfsd`, an instance of  [ipfs-api](https://github.com/ipfs/js-ipfs-api) attached to the newly created ipfs node   
-
-### IPFS Daemon Controller (ipfsd)
-
-> The IPFS daemon controller that allows interacting with the spawned IPFS process
 
-#### `apiAddr` (getter) 
+`callback` - is a function with the signature `function (err, ipfsd)` where:
+  - `err` - is the error set if spawning the node is unsuccessful
+  - `ipfsd` - is the daemon controller instance: 
+    - `api` - a property of `ipfsd`, an instance of  [ipfs-api](https://github.com/ipfs/js-ipfs-api) attached to the newly created ipfs node   
 
-> Get the address (multiaddr) of connected IPFS API.
+### IPFS Daemon Controller (`ipfsd`)
 
-- returns multiaddr
+The IPFS daemon controller (`ipfsd`) allows you to interact with the spawned IPFS daemon.
 
-#### `gatewayAddr` (getter)
+#### `ipfsd.apiAddr` (getter)
 
-> Get the address (multiaddr) of connected IPFS HTTP Gateway.
+Get the address (multiaddr) of connected IPFS API. Returns a multiaddr,
 
-- returns multiaddr
+#### `ipfsd.gatewayAddr` (getter)
 
-#### `repoPath` (getter)
+Get the address (multiaddr) of connected IPFS HTTP Gateway. Returns a multiaddr.
 
-> Get the current repo path.
+#### `ipfsd.repoPath` (getter)
 
-- returns string
+Get the current repo path. Returns string
 
-#### `started` (getter)
+#### `ipfsd.started` (getter)
 
->  Is the node started.
-
-- returns boolean
+Is the node started. Returns a boolean.
  
-#### `init ([initOpts], callback)`
+#### `init([initOpts], callback)`
 
-> Initialize a repo.
+Initialize a repo. 
 
-- `initOpts` (optional) - options object with the following entries
+`initOpts` (optional) is an object with the following properties:
   - `keysize` (default 2048) - The bit size of the identiy key.
   - `directory` (default IPFS_PATH if defined, or ~/.ipfs for go-ipfs and ~/.jsipfs for js-ipfs) - The location of the repo.
-  - `function (Error, Node)` callback - receives an instance of this Node on success or an instance of `Error` on failure
-
-
-#### `cleanup (callback)`
-
-> Delete the repo that was being used. If the node was marked as `disposable` this will be called automatically when the process is exited.
+ 
+`callback` is a function with the signature `function (Error, ipfsd)` where `err` is an Error in case something goes wrong and `ipfsd` is the daemon controller instance.
 
-- `function(Error)` callback
+#### `ipfsd.cleanup(callback)`
 
-#### `start (flags, callback)`
+Delete the repo that was being used. If the node was marked as `disposable` this will be called automatically when the process is exited.
 
-> Start the daemon.
+`callback` is a function with the signature `function(err)`.
 
-- `flags` - Flags array to be passed to the `ipfs daemon` command.
-- `function(Error, IpfsApi)}` callback - function that receives an instance of `ipfs-api` on success or an instance of `Error` on failure
+#### `ipfsd.start(flags, callback)`
 
+Start the daemon.
 
-#### `stop (callback)`
+`flags` - Flags array to be passed to the `ipfs daemon` command.
 
-> Stop the daemon.
+`callback` is a function with the signature `function(err, ipfsApi)}` that receives an instance of `ipfs-api` on success or an instance of `Error` on failure
 
-- `function(Error)` callback - function that receives an instance of `Error` on failure
 
-#### `killProcess (callback)`
+#### `ipfsd.stop(callback)`
 
-> Kill the `ipfs daemon` process.
+Stop the daemon.
 
-First `SIGTERM` is sent, after 10.5 seconds `SIGKILL` is sent if the process hasn't exited yet.
+`callback` is a function with the signature `function(err)` callback - function that receives an instance of `Error` on failure
 
-- `function()` callback - Called once the process is killed
+#### `ipfsd.killProcess (callback)`
 
+Kill the `ipfs daemon` process.
 
-#### `pid ()`
+First a `SIGTERM` is sent, after 10.5 seconds `SIGKILL` is sent if the process hasn't exited yet.
 
-> Get the pid of the `ipfs daemon` process.
+`callback` is a function with the signature `function()` called once the process is killed
 
-- returns the pid number
+#### `ipfsd.pid ()`
 
+Get the pid of the `ipfs daemon` process. Returns the pid number
 
-#### `getConfig (key, callback)`
+#### `ipfsd.getConfig(key, callback)`
 
-> Call `ipfs config`
+Returns the output of an `ipfs config` command. If no `key` is passed, the whole config is returned as an object.
 
-If no `key` is passed, the whole config is returned as an object.
+`key` (optional) - A specific config to retrieve.
 
-- `key` (optional) - A specific config to retrieve.
-- `function(Error, (Object|string)` callback - function that receives an object or string on success or an `Error` instance on failure
+`callback` is a function with the signature `function(err, (Object|string)` that receives an object or string on success or an `Error` instance on failure
 
+#### `ipfsd.setConfig (key, value, callback)`
 
-#### `setConfig (key, value, callback)`
+Set a config value.
 
-> Set a config value.
+`key` - the key of the config entry to change/set 
 
-- `key` - the key of the config entry to change/set 
-- `value` - the config value to change/set
-- `function(Error)` callback - function that receives an `Error` instance on failure
+`value` - the config value to change/set
 
+`callback` is a function with the signature `function(err)` callback - function that receives an `Error` instance on failure
 
-#### `version (callback)`
+#### `ipfsd.version(callback)`
 
-> Get the version of ipfs
+Get the version of ipfs
 
-- `function(Error, string)` callback
+`callback` is a function with the signature `function(err, version)`
    
 ### IPFS Client (`ipfsd.api`)
 
-> An instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api#api)
+An instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api#api) that is used to interact with the daemon.
 
 This instance is returned for each successfully started IPFS daemon, when either `df.spawn({start: true})` (the default) is called, or `ipfsd.start()` is invoked in the case of nodes that were spawned with `df.spawn({start: false})`. 
    
 ### Packaging
 
-`ipfsd-ctl` can be packaged in Electron applications, but the ipfs binary
-has to be excluded from asar (Electron Archives),
+`ipfsd-ctl` can be packaged in Electron applications, but the ipfs binary has to be excluded from asar (Electron Archives),
 [read more about unpack files from asar](https://electron.atom.io/docs/tutorial/application-packaging/#adding-unpacked-files-in-asar-archive).
-`ipfsd-ctl` will try to detect if used from within an `app.asar` archive
-and tries to resolve ipfs from `app.asar.unpacked`. The ipfs binary is part of
-the `go-ipfs-dep` module.
+
+`ipfsd-ctl` will try to detect if used from within an `app.asar` archive and tries to resolve ipfs from `app.asar.unpacked`. The ipfs binary is part of the `go-ipfs-dep` module.
 
 ```bash
 electron-packager ./ --asar.unpackDir=node_modules/go-ipfs-dep
