From c7342aa90edae40560e1486b48002ecd292828dc Mon Sep 17 00:00:00 2001
From: David Worms <david@adaltas.com>
Date: Sun, 30 Jul 2017 13:00:37 +0200
Subject: [PATCH] docker: doc cleanup #119

---
 CHANGELOG.md                       |  2 +
 src/docker/build.coffee.md         | 87 +++++++++++++-------------
 src/docker/checksum.coffee.md      | 18 +++---
 src/docker/cp.coffee.md            | 14 +++--
 src/docker/exec.coffee.md          | 34 +++++------
 src/docker/kill.coffee.md          | 24 +++-----
 src/docker/load.coffee.md          | 22 +++----
 src/docker/logout.coffee.md        | 20 +++---
 src/docker/pause.coffee.md         | 24 +++-----
 src/docker/pull.coffee.md          | 20 +++---
 src/docker/restart.coffee.md       | 14 ++---
 src/docker/rm.coffee.md            | 26 +++++---
 src/docker/rmi.coffee.md           |  8 +--
 src/docker/run.coffee.md           | 98 ++++++++++++++----------------
 src/docker/save.coffee.md          | 10 +--
 src/docker/service.coffee.md       |  1 +
 src/docker/start.coffee.md         | 30 ++++-----
 src/docker/status.coffee.md        | 28 ++++-----
 src/docker/stop.coffee.md          | 24 +++-----
 src/docker/unpause.coffee.md       | 20 +++---
 src/docker/volume_create.coffee.md | 19 ++++--
 src/docker/volume_rm.coffee.md     | 11 +++-
 src/docker/wait.coffee.md          | 24 +++-----
 src/misc/docker.coffee.md          |  1 +
 24 files changed, 259 insertions(+), 320 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 073f60092..b90d61540 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,8 @@
 
 ## Trunk
 
+* docker: doc cleanup #119
+* misc: merge support null as first argument
 * rubygem: source support glob expression
 * rubygem: improve test suport and resilience
 * rubygem: new fetch, install and remove actions
diff --git a/src/docker/build.coffee.md b/src/docker/build.coffee.md
index f8b789f5b..48a0b8878 100644
--- a/src/docker/build.coffee.md
+++ b/src/docker/build.coffee.md
@@ -13,29 +13,29 @@ Status unmodified if the repository is identical to a previous one
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `image` (string)   
-  Name of the image. __Mandatory__   
+  Name of the image, required.
 * `tag` (string)   
-  Tag of the image   
+  Tag of the image.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `file`   
-  Dockerfile path   
+  Path to Dockerfile.
 * `content` (string | [string])   
-  Use this text to build the repository.   
+  Use this text to build the repository.
 * `quiet` (boolean)   
-  Suppress the verbose output generated by the containers. Default to false   
+  Suppress the verbose output generated by the containers. Default to false
 * `rm` (boolean)   
-  Remove intermediate containers after build. Default to true   
+  Remove intermediate containers after build, default to true.
 * `force_rm` (boolean)   
-  Always remove intermediate containers during build. Default to false   
+  Always remove intermediate containers during build, default to false.
 * `no_cache` (boolean)   
-  Do not use cache when building the repository. Default to false   
+  Do not use cache when building the repository, default to false.
 * `build_arg` ("k=v" | [])   
-  Send arguments to the build (Must match an ARG command).   
+  Send arguments to the build (Must match an ARG command).
 * `cwd` (string)   
-  change the working directory for the build.   
+  change the working directory for the build.
 
 ## Callback parameters
 
@@ -52,37 +52,36 @@ Status unmodified if the repository is identical to a previous one
 
 ## Example
 
-1- builds a repository from dockerfile without any resourcess
+### Builds a repository from dockerfile without any resourcess
 
 ```javascript
 nikita.docker.build({
-  image: 'ryba/targe-build'
+  image: 'ryba/targe-build',
   source: '/home/ryba/Dockerfile'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
-})
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container built: ' + status);
+});
 ```
 
-2- builds an repository from dockerfile with external resources
+### Builds an repository from dockerfile with external resources
 
 In this case nikita download all the external files into a resources directory in the same location
-than the Dockerfile.
-The Dockerfile content:   "
-                            FROM centos6
-                            ADD resources/package.tar.gz /tmp/
-                            ADD resources/configuration.sh /tmp/
-                          "
+than the Dockerfile. The Dockerfile content:
+
+```dockerfile
+FROM centos7
+ADD resources/package.tar.gz /tmp/
+ADD resources/configuration.sh /tmp/
+```
+
 Build directory tree :
-                          ├── Dockerfile
-                          ├── resources
-                          │   ├── package.tar.gz
-                          │   ├── configuration.sh
+
+```
+├── Dockerfile
+├── resources
+│   ├── package.tar.gz
+│   ├── configuration.sh
+```
 
 ```javascript
 nikita.docker.build({
@@ -90,25 +89,21 @@ nikita.docker.build({
   tag: 'ryba/target-build'
   source: '/home/ryba/Dockerfile'
   resources: ['http://url.com/package.tar.gz/','/home/configuration.sh']
-}, function(err, is_built, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_built){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
-})
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container built: ' + status);
+});
 ```
 
-3- builds an repository from stdin
+### Builds an repository from stdin
 
 ```javascript
 nikita.docker.build({
-  ssh: ssh
+  ssh: ssh,
   tag: 'ryba/target-build'
   content: "FROM ubuntu\nRUN echo 'helloworld'"
-}, function(err, is_built, stdout, stderr){})
+}, function(err, is_built, stdout, stderr){
+  console.log( err ? err.message : 'Container built: ' + status);
+});
 ``
 
 ## Source Code
diff --git a/src/docker/checksum.coffee.md b/src/docker/checksum.coffee.md
index 6c6904766..9531a3434 100644
--- a/src/docker/checksum.coffee.md
+++ b/src/docker/checksum.coffee.md
@@ -6,26 +6,26 @@ Return the checksum of repository:tag, if it exists. Function not native to dock
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `cwd` (string)   
-  change the working directory for the build.   
+  change the working directory for the build.
 * `image` (string)   
-  Name of the image, required.   
+  Name of the image, required.
 * `repository` (string)   
-  Alias of image.   
+  Alias of image.
 * `machine` (string)   
-  Name of the docker-machine, required if using docker-machine.   
+  Name of the docker-machine, required if using docker-machine.
 * `tag` (string)   
-  Tag of the image, default to latest.   
+  Tag of the image, default to latest.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
+  Error object if any.
 * `status`   
-  True if command was executed.   
+  True if command was executed.
 * `checksum`   
-  Image cheksum if it exist, false otherwise.   
+  Image cheksum if it exist, false otherwise.
 
 ## Source Code
 
diff --git a/src/docker/cp.coffee.md b/src/docker/cp.coffee.md
index daa2eaa45..ae37286db 100644
--- a/src/docker/cp.coffee.md
+++ b/src/docker/cp.coffee.md
@@ -16,13 +16,13 @@ Note, stream are not yet supported.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `machine` (string)   
-  Name of the docker-machine, required if using docker-machine or boot2docker.   
+  Name of the docker-machine, required if using docker-machine or boot2docker.
 * `source` (string)   
-  The path to upload or the container followed by the path to download.   
+  The path to upload or the container followed by the path to download.
 * `target` (string)   
-  The path to download or the container followed by the path to upload.   
+  The path to download or the container followed by the path to upload.
 
 ## Uploading a file
 
@@ -37,9 +37,11 @@ nikita.docker({
 
 ```javascript
 nikita.docker({
-  source: 'my_container:/path/to/source'
+  source: 'my_container:/path/to/source',
   target: writable_stream or '/path/to/target'
-}, function(err, status){})
+}, function(err, status){
+  console.log( err ? err.message : 'Container copied: ' + status);
+});
 ```
 
 ## Source Code
diff --git a/src/docker/exec.coffee.md b/src/docker/exec.coffee.md
index 23dc8ea3b..31285c82b 100644
--- a/src/docker/exec.coffee.md
+++ b/src/docker/exec.coffee.md
@@ -6,27 +6,27 @@ Run a command in a running container
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.
 * `code_skipped` (int | array)   
-  The exit code(s) to skip.   
+  The exit code(s) to skip.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine.   
+  Name of the docker-machine, required using docker-machine.
 * `service` (boolean)   
-  if true, run container as a service, else run as a command, true by default.   
+  if true, run container as a service, else run as a command, true by default.
 * `uid` (name | uid)   
-  Username or uid.   
+  Username or uid.
 * `gid` (name | gid)   
-  Groupname or gid.   
+  Groupname or gid.
 
 
 ## Callback parameters
 
 * `err`   
   Error object if any.   
-* `executed`   
-  if command was executed   
+* `status`   
+  True if command was executed in container.
 * `stdout`   
   Stdout value(s) unless `stdout` option is provided.   
 * `stderr`   
@@ -36,18 +36,12 @@ Run a command in a running container
 
 ```javascript
 nikita.docker({
-  ssh: ssh
-  container: 'myContainer'
+  ssh: ssh,
+  container: 'myContainer',
   cmd: '/bin/bash -c "echo toto"'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
-})
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Command executed: ' + status);
+});
 ```
 
 ## Source Code
diff --git a/src/docker/kill.coffee.md b/src/docker/kill.coffee.md
index 1f3a0bbae..f3bda380b 100644
--- a/src/docker/kill.coffee.md
+++ b/src/docker/kill.coffee.md
@@ -9,35 +9,29 @@ SIGNAL is not sent.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
   Name/ID of the container. __Mandatory__   
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine.   
+  Name of the docker-machine. __Mandatory__ if using docker-machine.
 * `signal` (int|string)   
-  Use a specified signal. SIGKILL by default   
+  Use a specified signal. SIGKILL by default.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True if container was killed.
 
 ## Example
 
 ```javascript
 nikita.docker.kill({
-  container: 'toto'
+  container: 'toto',
   signal: 9
-}, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status){  
+  console.log( err ? err.message : 'Container killed: ' + status);
 })
 ```
 
diff --git a/src/docker/load.coffee.md b/src/docker/load.coffee.md
index ddb7dadc6..36181972f 100644
--- a/src/docker/load.coffee.md
+++ b/src/docker/load.coffee.md
@@ -6,16 +6,16 @@ Load Docker images
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `input` (string)   
-  TAR archive file to read from   
+  TAR archive file to read from.
 * `source` (string)   
-  Alias for the "input" option.   
+  Alias for the "input" option.
 * `checksum` (string)   
-  If provided, will check if attached input archive to checksum already exist.   
-  Not native to docker. But implemented to get better performance.   
+  If provided, will check if attached input archive to checksum already exist.
+  Not native to docker. But implemented to get better performance.
 
 ## Callback parameters
 
@@ -35,14 +35,8 @@ nikita.docker.load({
   image: 'nikita/load_test:latest',
   machine: machine,
   source: source + "/nikita_load.tar"
-}, function(err, loaded, stdout, stderr) {
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status, stdout, stderr) {
+  console.log( err ? err.message : 'Container loaded: ' + status);
 })
 ```
 
diff --git a/src/docker/logout.coffee.md b/src/docker/logout.coffee.md
index 4f7188e5b..684b7d11e 100644
--- a/src/docker/logout.coffee.md
+++ b/src/docker/logout.coffee.md
@@ -7,16 +7,16 @@ specified  is the default.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `registry` (string)   
-  Address of the registry server. "https://index.docker.io/v1/" by default   
+  Address of the registry server, default to "https://index.docker.io/v1/".
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `code` (int|array)   
-  Expected code(s) returned by the command, int or array of int, default to 0.   
+  Expected code(s) returned by the command, int or array of int, default to 0.
 * `code_skipped`   
   Expected code(s) returned by the command if it has no effect, executed will
-  not be incremented, int or array of int.   
+  not be incremented, int or array of int.
 
 ## Callback parameters
 
@@ -30,14 +30,8 @@ specified  is the default.
 ```javascript
 nikita.docker.pause({
   container: 'toto'
-}, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status){
+  console.log( err ? err.message : 'Logout: ' + status);
 })
 ```
 
diff --git a/src/docker/pause.coffee.md b/src/docker/pause.coffee.md
index 024a3931f..14f1d6dda 100644
--- a/src/docker/pause.coffee.md
+++ b/src/docker/pause.coffee.md
@@ -8,35 +8,29 @@ Pause all processes within a container
 * `boot2docker` (boolean)   
   Whether to use boot2docker or not, default to false.   
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required.
 * `code` (int|array)   
-  Expected code(s) returned by the command, int or array of int, default to 0.   
+  Expected code(s) returned by the command, int or array of int, default to 0.
 * `code_skipped`   
   Expected code(s) returned by the command if it has no effect, executed will
-  not be incremented, int or array of int.   
+  not be incremented, int or array of int.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True if container was pulled.
 
 ## Example
 
 ```javascript
 nikita.docker.pause({
   container: 'toto'
-}, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status){
+  console.log( err ? err.message : 'Container paused: ' + status);
 })
 ```
 
diff --git a/src/docker/pull.coffee.md b/src/docker/pull.coffee.md
index fe653f8e7..64caf681c 100644
--- a/src/docker/pull.coffee.md
+++ b/src/docker/pull.coffee.md
@@ -17,13 +17,13 @@ Pull a container
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True if container was pulled.
 * `stdout`   
-  Stdout value(s) unless `stdout` option is provided.   
+  Stdout value(s) unless `stdout` option is provided.
 * `stderr`   
-  Stderr value(s) unless `stderr` option is provided.   
+  Stderr value(s) unless `stderr` option is provided.
 
 ## Example
 
@@ -32,14 +32,8 @@ Pull a container
 ```javascript
 nikita.docker_pull({
   tag: 'postgres'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container pulled: ' + status);
 })
 ```
 
diff --git a/src/docker/restart.coffee.md b/src/docker/restart.coffee.md
index 96eceafe3..f76905f43 100644
--- a/src/docker/restart.coffee.md
+++ b/src/docker/restart.coffee.md
@@ -23,22 +23,16 @@ Start stopped containers. Or stop/starts started container
 
 * `err`   
   Error object if any.   
-* `executed`   
-  if command was executed   
+* `status`   
+  True if container was restarted.  
 
 ## Example
 
 ```javascript
 nikita.docker.restart({
   container: 'toto'
-}, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status){
+  console.log( err ? err.message : 'Container restarted: ' + status);
 })
 ```
 
diff --git a/src/docker/rm.coffee.md b/src/docker/rm.coffee.md
index 1fb17f43a..066d545cc 100644
--- a/src/docker/rm.coffee.md
+++ b/src/docker/rm.coffee.md
@@ -7,27 +7,35 @@ force options is set.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if docker-machine installed   
+  Name of the docker-machine, required if docker-machine installed.
 * `link` (boolean)   
-  Remove the specified link   
+  Remove the specified link.
 * `volumes` (boolean)   
-  Remove the volumes associated with the container   
+  Remove the volumes associated with the container.
 * `force` (boolean)   
-  Force the removal of a running container (uses SIGKILL)   
+  Force the removal of a running container (uses SIGKILL).
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True if container was removed.
 
 ## Example Code
 
+```javascript
+nikita.docker.rm({
+  container: 'toto'
+}, function(err, status){
+  console.log( err ? err.message : 'Container removed: ' + status);
+})
+```
+
 ## Source Code
 
     module.exports = (options, callback) ->
diff --git a/src/docker/rmi.coffee.md b/src/docker/rmi.coffee.md
index 85831054c..1dc12cb6f 100644
--- a/src/docker/rmi.coffee.md
+++ b/src/docker/rmi.coffee.md
@@ -7,13 +7,13 @@ force options is set.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `image` (string)   
-  Name of the image. __Mandatory__   
+  Name of the image, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if docker-machine installed   
+  Name of the docker-machine, required if docker-machine installed.
 * `no_prune` (boolean)   
-  Do not delete untagged parents   
+  Do not delete untagged parents.
 
 ## Source Code
 
diff --git a/src/docker/run.coffee.md b/src/docker/run.coffee.md
index 961e8d7e5..8dbdd3f58 100644
--- a/src/docker/run.coffee.md
+++ b/src/docker/run.coffee.md
@@ -6,92 +6,92 @@ Run Docker Containers
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Alias of name   
+  Alias of name.
 * `name` (string)   
-   Assign a name to the container to run.   
+   Assign a name to the container to run.
 * `image` (string)   
-  Name/ID of base image. __Mandatory__   
+  Name/ID of base image, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `cmd` (string)   
-  Overwrite the default ENTRYPOINT of the image   
-  Equivalent to --entrypoint docker parameter   
+  Overwrite the default ENTRYPOINT of the image, equivalent to 
+  `--entrypoint docker parameter`
 * `hostname` (string)   
-  Hostname in the docker container   
+  Hostname in the docker container.
 * `port` ( 'int:int' | [] )   
-  port mapping   
+  Port mapping.
 * `volume` ( 'path:path' | [] )   
-  path mapping   
+  Path mapping.
 * `device` ('path' | [] )   
-  Send host device(s) to container   
+  Send host device(s) to container.
 * `dns` (ip-address | [] )   
-  Set custom DNS server(s)   
+  Set custom DNS server(s).
 * `dns_search` (ip-address | [] )   
-  Set custom DNS search domain(s)   
+  Set custom DNS search domain(s).
 * `expose` ( int | string | [] )   
-  Export port(s)   
+  Export port(s).
 * `link` ( containerName | containerID | [] )   
-  Link to other container(s)   
+  Link to other container(s).
 * `label` (string | [] )   
-  Set meta data on a container   
+  Set meta data on a container.
 * `label_file` (path)   
-  Read in a line delimited file of labels   
+  Read in a line delimited file of labels.
 * `add_host` ('host:ip' | [] )   
-  Add a custom host-to-IP mapping (host:ip)   
+  Add a custom host-to-IP mapping (host:ip).
 * `cap_add` ( | [] )   
-  Add Linux Capabilities   
+  Add Linux Capabilities.
 * `cap_drop` ( | [] )   
-  Drop Linux Capabilities   
+  Drop Linux Capabilities.
 * `blkio_weight` (int)   
-  Block IO (relative weight), between 10 and 1000   
+  Block IO (relative weight), between 10 and 1000.
 * `cgroup_parent`   
-  Optional parent cgroup for the container   
+  Optional parent cgroup for the container.
 * `cid_file` ( path )   
-  Write the container ID to the file   
+  Write the container ID to the file.
 * `cpuset_cpus` (string)   
-  CPUs in which to allow execution (ex: 0-3 0,1 ...)   
+  CPUs in which to allow execution (ex: 0-3 0,1 ...).
 * `entrypoint` ()   
-  Overwrite the default ENTRYPOINT of the image   
+  Overwrite the default ENTRYPOINT of the image.
 * `ipc` ()   
-  IPC namespace to use   
+  IPC namespace to use.
 * `ulimit`  ( | [] )   
-  Ulimit options   
+  Ulimit options.
 * `volumes_from` (containerName | containerID | [] )   
-  Mount volumes from the specified container(s)   
+  Mount volumes from the specified container(s).
 * `detach` (boolean)   
-  if true, run container in background   
+  if true, run container in background.
 * `env` ('VAR=value' | [] )   
-  Environment variables for the container.   
+  Environment variables for the container..
 * `env_file` ( path | [] )   
-  Read in a file of environment variables   
+  Read in a file of environment variables.
 * `rm` (boolean)   
-  delete the container when it ends. True by default   
+  Delete the container when it ends. True by default.
 * `cwd` (path)   
-  working directory of container   
+  Working directory of container.
 * `net` (string)   
-  Set the Network mode for the container   
+  Set the Network mode for the container.
 * `pid` (string)   
-  PID namespace to use   
+  PID namespace to use.
 * `publish_all` (boolean)   
-  Publish all exposed ports to random ports   
+  Publish all exposed ports to random ports.
 * `code`   (int|array)   
-  Expected code(s) returned by the command, int or array of int, default to 0.   
+  Expected code(s) returned by the command, int or array of int, default to 0..
 * `code_skipped`   
-  Expected code(s) returned by the command if it has no effect, executed will   
-  not be incremented, int or array of int.   
+  Expected code(s) returned by the command if it has no effect, executed will
+  not be incremented, int or array of int.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True unless contaianer was already running.
 * `stdout`   
-  Stdout value(s) unless `stdout` option is provided.   
+  Stdout value(s) unless `stdout` option is provided.
 * `stderr`   
-  Stderr value(s) unless `stderr` option is provided.   
+  Stderr value(s) unless `stderr` option is provided.
 
 ## Example
 
@@ -102,14 +102,8 @@ nikita.docker({
   image: 'test-image'
   env: ["FOO=bar",]
   entrypoint: '/bin/true'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container state changed to running: ' + status);
 })
 ```
 
diff --git a/src/docker/save.coffee.md b/src/docker/save.coffee.md
index 360afd6eb..c97bcbe24 100644
--- a/src/docker/save.coffee.md
+++ b/src/docker/save.coffee.md
@@ -43,14 +43,8 @@ nikita.docker({
   image: 'test-image'
   compression: 'gzip'
   entrypoint: '/bin/true'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container saved: ' + status);
 })
 ```
 
diff --git a/src/docker/service.coffee.md b/src/docker/service.coffee.md
index 65a1c7c6d..be69e59c4 100644
--- a/src/docker/service.coffee.md
+++ b/src/docker/service.coffee.md
@@ -3,6 +3,7 @@
 
 Run a container in a service mode. This module is just a wrapper for docker.run
 with correct options.
+
 Indeed, in a service mode, the container must be detached and NOT removed by default
 after execution. 
 
diff --git a/src/docker/start.coffee.md b/src/docker/start.coffee.md
index f6db7102d..6ff1fe074 100644
--- a/src/docker/start.coffee.md
+++ b/src/docker/start.coffee.md
@@ -5,29 +5,29 @@ Restart containers
 
 ## Options
 
-*   `boot2docker` (boolean)   
+* `boot2docker` (boolean)   
   Whether to use boot2docker or not, default to false.   
-*   `container` (string)   
+* `container` (string)   
   Name/ID of the container. __Mandatory__   
-*   `machine` (string)   
+* `machine` (string)   
   Name of the docker-machine. __Mandatory__ if using docker-machine   
-*   `attach` (boolean)   
+* `attach` (boolean)   
   attach STDOUT/STDERR. False by default   
-*   `code` (int|array)   
+* `code` (int|array)   
   Expected code(s) returned by the command, int or array of int, default to 0.   
-*   `code_skipped`   
+* `code_skipped`   
   Expected code(s) returned by the command if it has no effect, executed will   
   not be incremented, int or array of int.   
 
 ## Callback parameters
 
-*   `err`   
+* `err`   
   Error object if any.   
-*   `executed`   
-  if command was executed   
-*   `stdout`   
+* `status`   
+  True unless container was already started.
+* `stdout`   
   Stdout value(s) unless `stdout` option is provided.   
-*   `stderr`   
+* `stderr`   
   Stderr value(s) unless `stderr` option is provided.   
 
 ## Example
@@ -39,13 +39,7 @@ nikita.docker.start({
   container: 'toto',
   attach: true
 }, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+  console.log( err ? err.message : 'Container state changed to started: ' + status);
 })
 ```
 
diff --git a/src/docker/status.coffee.md b/src/docker/status.coffee.md
index f3a7ed26f..9de47a38d 100644
--- a/src/docker/status.coffee.md
+++ b/src/docker/status.coffee.md
@@ -6,22 +6,22 @@ Return true if container is running. This function is not native to docker.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
-* `container` (string|array). __Mandatory__   
-  Name or Id of the container.   
+  Whether to use boot2docker or not, default to false.
+* `container` (string|array)   
+  Name or Id of the container, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  Wether the container is running or not.   
+  Error object if any.
+* `status`   
+  True if container is running.
 * `stdout`   
-  Stdout value(s) unless `stdout` option is provided.   
+  Stdout value(s) unless `stdout` option is provided.
 * `stderr`   
-  Stderr value(s) unless `stderr` option is provided.   
+  Stderr value(s) unless `stderr` option is provided.
 
 ## Example
 
@@ -32,14 +32,8 @@ nikita.docker({
   image: 'test-image'
   compression: 'gzip'
   entrypoint: '/bin/true'
-}, function(err, is_true, stdout, stderr){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+}, function(err, status, stdout, stderr){
+  console.log( err ? err.message : 'Container running: ' + status);
 })
 ```
 
diff --git a/src/docker/stop.coffee.md b/src/docker/stop.coffee.md
index 004f32c71..d8700d82e 100644
--- a/src/docker/stop.coffee.md
+++ b/src/docker/stop.coffee.md
@@ -1,25 +1,25 @@
 
 # `nikita.docker.stop(options, [callback])`
 
-Stop started containers
+Stop started containers.
 
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `timeout` (int)   
-  Seconds to wait for stop before killing it   
+  Seconds to wait for stop before killing it
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  Wether the container was stoped or not.   
+  Error object if any.
+* `status`   
+  True unless container was already stopped.
 
 ## Example
 
@@ -27,13 +27,7 @@ Stop started containers
 nikita.docker.stop({
   container: 'toto'
 }, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+  console.log( err ? err.message : 'Container state changed to stopped: ' + status);
 })
 ```
 
diff --git a/src/docker/unpause.coffee.md b/src/docker/unpause.coffee.md
index 34da0f0ef..1b15a968b 100644
--- a/src/docker/unpause.coffee.md
+++ b/src/docker/unpause.coffee.md
@@ -6,18 +6,18 @@ Unpause all processes within a container
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, required.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 
 ## Callback parameters
 
 * `err`   
-  Error object if any.   
-* `executed`   
-  if command was executed   
+  Error object if any.
+* `status`   
+  True if container was unpaused.
 
 ## Example
 
@@ -25,13 +25,7 @@ Unpause all processes within a container
 nikita.docker.pause({
   container: 'toto'
 }, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+  console.log( err ? err.message : 'Container was unpaused: ' + status);
 })
 ```
 
diff --git a/src/docker/volume_create.coffee.md b/src/docker/volume_create.coffee.md
index b7f5f0a77..ac360141d 100644
--- a/src/docker/volume_create.coffee.md
+++ b/src/docker/volume_create.coffee.md
@@ -6,25 +6,32 @@ Create a volume.
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `driver` (string)   
-  Specify volume driver name.   
+  Specify volume driver name.
 * `label` (string|array)   
-  Set metadata for a volume.   
+  Set metadata for a volume.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, required if using docker-machine.
 * `name` (string)   
-  Specify volume name.   
+  Specify volume name.
 * `opt` (string|array)   
   Set driver specific options.
 
+## Callback parameters
+
+* `err`   
+  Error object if any.   
+* `status`   
+  True is volume was created.
+
 ## Example
 
 ```javascript
 nikita.docker.pause({
   name: 'my_volume'
 }, function(err, created){
-  console.log(err or 'Status: '+created);
+  console.log( err ? err.message : 'Volume created: ' + status);
 })
 ```
 
diff --git a/src/docker/volume_rm.coffee.md b/src/docker/volume_rm.coffee.md
index c835c0a23..834a1ba57 100644
--- a/src/docker/volume_rm.coffee.md
+++ b/src/docker/volume_rm.coffee.md
@@ -14,13 +14,20 @@ Remove a volume.
 * `name` (string)   
   Specify volume name.   
 
+## Callback parameters
+
+* `err`   
+  Error object if any.   
+* `status`   
+  True is volume was removed.
+
 ## Example
 
 ```javascript
 nikita.docker.volume_rm({
   name: 'my_volume'
-}, function(err, removed){
-  console.log(err or 'Status'+removed);
+}, function(err, status){
+  console.log( err ? err.message : 'Volume removed: ' + status);
 })
 ```
 
diff --git a/src/docker/wait.coffee.md b/src/docker/wait.coffee.md
index 27fb20243..c3c01de3c 100644
--- a/src/docker/wait.coffee.md
+++ b/src/docker/wait.coffee.md
@@ -1,28 +1,28 @@
 
 # `nikita.docker.wait(options, [callback])`
 
-Block until a container stops
+Block until a container stops.
 
 ## Options
 
 * `boot2docker` (boolean)   
-  Whether to use boot2docker or not, default to false.   
+  Whether to use boot2docker or not, default to false.
 * `container` (string)   
-  Name/ID of the container. __Mandatory__   
+  Name/ID of the container, optional.
 * `machine` (string)   
-  Name of the docker-machine. __Mandatory__ if using docker-machine   
+  Name of the docker-machine, optional if using docker-machine.
 * `code` (int|array)   
-  Expected code(s) returned by the command, int or array of int, default to 0.   
+  Expected code(s) returned by the command, int or array of int, default to 0.
 * `code_skipped`   
   Expected code(s) returned by the command if it has no effect, executed will
-  not be incremented, int or array of int.   
+  not be incremented, int or array of int.
 
 ## Callback parameters
 
 * `err`   
   Error object if any.   
-* `executed`   
-  if command was executed   
+* `status`   
+  True unless container was already stopped.
 
 ## Example
 
@@ -30,13 +30,7 @@ Block until a container stops
 nikita.docker.wait({
   container: 'toto'
 }, function(err, is_true){
-  if(err){
-    console.log(err.message);
-  }else if(is_true){
-    console.log('OK!');
-  }else{
-    console.log('Ooops!');
-  }
+  console.log( err ? err.message : 'Volume removed: ' + status);
 })
 ```
 
diff --git a/src/misc/docker.coffee.md b/src/misc/docker.coffee.md
index 66c5b089e..353af13e2 100644
--- a/src/misc/docker.coffee.md
+++ b/src/misc/docker.coffee.md
@@ -58,5 +58,6 @@
       eval $docker #{docker.opts} #{cmd}
       """
     # Reformat error message if any
+    # TODO: rename this function as format_error
     module.exports.callback = (err, executed, stdout, stderr) ->
       throw Error stderr.trim().replace 'Error response from daemon: ', '' if err and /^Error response from daemon/.test stderr