update CLI & api docs

Docker-DCO-1.1-Signed-off-by: Adrien Folie <folie.adrien@gmail.com> (github: folieadrien)

docs/man/docker-rm.1.md

@@ -6,7 +6,8 @@ docker-rm - Remove one or more containers
 
 # SYNOPSIS
 **docker rm**
-[**-f**|**--force**[=*false*]]
+[**-s**|**--stop**[=*false*]]
+[**-k**|**--kill**[=*false*]]
 [**-l**|**--link**[=*false*]]
 [**-v**|**--volumes**[=*false*]]
  CONTAINER [CONTAINER...]
@@ -19,8 +20,11 @@ remove a running container unless you use the \fB-f\fR option. To see all
 containers on a host use the **docker ps -a** command.
 
 # OPTIONS
-**-f**, **--force**=*true*|*false*
-   Force removal of running container. The default is *false*.
+**-s**, **--stop**=*true*|*false*
+   Stop then remove a running container. The default is *false*.
+
+**-k**, **--kill**=*true*|*false*
+   Kill then remove a running container. The default is *false*.
 
 **-l**, **--link**=*true*|*false*
    Remove the specified link and not the underlying container. The default is *false*.

docs/sources/reference/api/docker_remote_api.md

@@ -42,6 +42,14 @@ You can still call an old version of the API using
 
 ### What's new
 
+`DELETE /containers/(id)`
+
+New! You can now use the `stop` parameter to stop running containers
+before removal (replace `force`).
+
+New! You can now use the `kill` parameter to kill running containers
+before removal.
+
 `GET /containers/(name)/json`
 
 **New!**

docs/sources/reference/commandline/cli.md

@@ -838,7 +838,8 @@ registry or to a self-hosted one.
 
     Remove one or more containers
 
-      -f, --force=false      Force removal of running container
+      -s, --stop=false       Stop and remove a running container
+      -k, --kill=false       Kill and remove a running container
       -l, --link=false       Remove the specified link and not the underlying container
       -v, --volumes=false    Remove the volumes associated with the container
 
@@ -863,6 +864,20 @@ This will remove the underlying link between `/webapp`
 and the `/redis` containers removing all
 network communication.
 
+    $ sudo docker rm --stop redis
+    redis
+ 
+The main process inside the container referenced under the link `/redis` will receive
+SIGTERM, and after a grace period, SIGKILL, then the container will be removed.
+
+    $ sudo docker rm --kill redis
+    redis
+
+The main process inside the container referenced under the link `/redis` will receive
+SIGKILL, then the container will be removed.
+
+NOTE: If you try to use `stop` and `kill` simultaneously, Docker will return an error.
+
     $ sudo docker rm $(docker ps -a -q)
 
 This command will delete all stopped containers. The command