Update to docker stats documentation

Signed-off-by: Michael Crosby <crosbymichael@gmail.com>

api/client/commands.go

@@ -2688,7 +2688,7 @@ func (s *containerStats) Display(w io.Writer) error {
 }
 
 func (cli *DockerCli) CmdStats(args ...string) error {
-	cmd := cli.Subcmd("stats", "CONTAINER", "Display live container stats based on resource usage", true)
+	cmd := cli.Subcmd("stats", "CONTAINER", "Display a live stream of one or more containers' resource usage statistics", true)
 	cmd.Require(flag.Min, 1)
 	utils.ParseFlags(cmd, args, true)
 

docker/flags.go

@@ -98,7 +98,7 @@ func init() {
 			{"save", "Save an image to a tar archive"},
 			{"search", "Search for an image on the Docker Hub"},
 			{"start", "Start a stopped container"},
-			{"stats", "Display live container stats based on resource usage"},
+			{"stats", "Display a live stream of one or more containers' resource usage statistics"},
 			{"stop", "Stop a running container"},
 			{"tag", "Tag an image into a repository"},
 			{"top", "Lookup the running processes of a container"},

docs/man/docker-stats.1.md

@@ -2,7 +2,7 @@
 % Docker Community
 % JUNE 2014
 # NAME
-docker-stats - Display live container stats based on resource usage.
+docker-stats - Display a live stream of one or more containers' resource usage statistics
 
 # SYNOPSIS
 **docker stats**
@@ -11,7 +11,7 @@ docker-stats - Display live container stats based on resource usage.
 
 # DESCRIPTION
 
-Display live container stats based on resource usage.
+Display a live stream of one or more containers' resource usage statistics
 
 # OPTIONS
 **--help**

docs/sources/reference/api/docker_remote_api.md

@@ -71,7 +71,7 @@ root filesystem as read only.
 `GET /containers/(id)/stats`
 
 **New!**
-This endpoint returns a stream of container stats based on resource usage.
+This endpoint returns a live stream of a container's resource usage statistics.
 
 
 ## v1.16

docs/sources/reference/api/docker_remote_api_v1.17.md

@@ -518,7 +518,7 @@ Status Codes:
 
 `GET /containers/(id)/stats`
 
-Returns a stream of json objects of the container's stats
+This endpoint returns a live stream of a container's resource usage statistics.
 
 **Example request**:
 

docs/sources/reference/commandline/cli.md

@@ -2005,11 +2005,11 @@ more details on finding shared images from the command line.
 
     Usage: docker stats [CONTAINERS]
 
-    Display live container stats based on resource usage
+    Display a live stream of one or more containers' resource usage statistics
 
       --help=false       Print usage
 
-Running `docker stats` on two redis containers
+Running `docker stats` on multiple containers
 
     $ sudo docker stats redis1 redis2
     CONTAINER           CPU %               MEM USAGE/LIMIT     MEM %               NET I/O
@@ -2017,12 +2017,11 @@ Running `docker stats` on two redis containers
     redis2              0.07%               2.746 MiB/64 MiB    4.29%               1.266 KiB/648 B
 
 
-When run on running containers live container stats will be streamed
-back and displayed to the client.  Stopped containers will not 
-receive any updates to their stats unless the container is started again.
+The `docker stats` command will only return a live stream of data for running 
+containers. Stopped containers will not return any data.
 
 > **Note:**
-> If you want more in depth resource usage for a container use the API endpoint
+> If you want more detailed information about a container's resource usage, use the API endpoint.
 
 ## stop