From b5d0380108dde9e96d51bb01821860a0799dee0d Mon Sep 17 00:00:00 2001
From: Peggy Li <peggyli.224@gmail.com>
Date: Wed, 25 Mar 2015 10:34:41 -0700
Subject: [PATCH 1/2] Add godoc-style docstrings to Cmd... methods

Signed-off-by: Peggy Li <peggyli.224@gmail.com>
---
 api/client/attach.go  | 3 +++
 api/client/build.go   | 5 +++++
 api/client/cli.go     | 2 +-
 api/client/client.go  | 5 +++++
 api/client/commit.go  | 3 +++
 api/client/cp.go      | 5 +++++
 api/client/create.go  | 3 +++
 api/client/diff.go    | 5 +++++
 api/client/events.go  | 3 +++
 api/client/exec.go    | 3 +++
 api/client/export.go  | 5 +++++
 api/client/help.go    | 5 +++++
 api/client/history.go | 3 +++
 api/client/images.go  | 3 +++
 api/client/import.go  | 5 +++++
 api/client/info.go    | 4 +++-
 api/client/inspect.go | 3 +++
 api/client/kill.go    | 4 +++-
 api/client/load.go    | 5 +++++
 api/client/login.go   | 6 +++++-
 api/client/logout.go  | 6 +++++-
 api/client/logs.go    | 3 +++
 api/client/pause.go   | 3 +++
 api/client/port.go    | 4 ++++
 api/client/ps.go      | 3 +++
 api/client/pull.go    | 3 +++
 api/client/push.go    | 3 +++
 api/client/rename.go  | 3 +++
 api/client/restart.go | 3 +++
 api/client/rmi.go     | 4 +++-
 api/client/run.go     | 3 +++
 api/client/save.go    | 5 +++++
 api/client/search.go  | 3 +++
 api/client/start.go   | 3 +++
 api/client/stats.go   | 5 +++++
 api/client/stop.go    | 5 +++++
 api/client/tag.go     | 3 +++
 api/client/top.go     | 3 +++
 api/client/unpause.go | 3 +++
 api/client/version.go | 6 +++++-
 api/client/wait.go    | 6 +++++-
 41 files changed, 152 insertions(+), 8 deletions(-)
 create mode 100644 api/client/client.go

diff --git a/api/client/attach.go b/api/client/attach.go
index e9232a104b..5b80485895 100644
--- a/api/client/attach.go
+++ b/api/client/attach.go
@@ -12,6 +12,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdAttach attaches to a running container.
+//
+// Usage: docker attach [OPTIONS] CONTAINER
 func (cli *DockerCli) CmdAttach(args ...string) error {
 	var (
 		cmd     = cli.Subcmd("attach", "CONTAINER", "Attach to a running container", true)
diff --git a/api/client/build.go b/api/client/build.go
index 91446132ab..78507c39b5 100644
--- a/api/client/build.go
+++ b/api/client/build.go
@@ -36,6 +36,11 @@ const (
 	tarHeaderSize = 512
 )
 
+// CmdBuild builds a new image from the source code at a given path.
+//
+// If '-' is provided instead of a path or URL, Docker will build an image from either a Dockerfile or tar archive read from STDIN.
+//
+// Usage: docker build [OPTIONS] PATH | URL | -
 func (cli *DockerCli) CmdBuild(args ...string) error {
 	cmd := cli.Subcmd("build", "PATH | URL | -", "Build a new image from the source code at PATH", true)
 	tag := cmd.String([]string{"t", "-tag"}, "", "Repository name (and optionally a tag) for the image")
diff --git a/api/client/cli.go b/api/client/cli.go
index e0ab4191bf..01b5f2e63f 100644
--- a/api/client/cli.go
+++ b/api/client/cli.go
@@ -64,7 +64,7 @@ func (cli *DockerCli) getMethod(args ...string) (func(...string) error, bool) {
 	return method.Interface().(func(...string) error), true
 }
 
-// Cmd executes the specified command
+// Cmd executes the specified command.
 func (cli *DockerCli) Cmd(args ...string) error {
 	if len(args) > 1 {
 		method, exists := cli.getMethod(args[:2]...)
diff --git a/api/client/client.go b/api/client/client.go
new file mode 100644
index 0000000000..4cfce5f684
--- /dev/null
+++ b/api/client/client.go
@@ -0,0 +1,5 @@
+// Package client provides a command-line interface for Docker.
+//
+// Run "docker help SUBCOMMAND" or "docker SUBCOMMAND --help" to see more information on any Docker subcommand, including the full list of options supported for the subcommand.
+// See https://docs.docker.com/installation/ for instructions on installing Docker.
+package client
diff --git a/api/client/commit.go b/api/client/commit.go
index c532fab0d0..4500f3b424 100644
--- a/api/client/commit.go
+++ b/api/client/commit.go
@@ -14,6 +14,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdAttach attaches to a running container.
+//
+// Usage: docker attach [OPTIONS] CONTAINER
 func (cli *DockerCli) CmdCommit(args ...string) error {
 	cmd := cli.Subcmd("commit", "CONTAINER [REPOSITORY[:TAG]]", "Create a new image from a container's changes", true)
 	flPause := cmd.Bool([]string{"p", "-pause"}, true, "Pause container during commit")
diff --git a/api/client/cp.go b/api/client/cp.go
index f2bedb0b10..19e050e16b 100644
--- a/api/client/cp.go
+++ b/api/client/cp.go
@@ -11,6 +11,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdCp copies files/folders from a path on the container to a directory on the host running the command.
+//
+// If HOSTDIR is '-', the data is written as a tar file to STDOUT.
+//
+// Usage: docker cp CONTAINER:PATH HOSTDIR
 func (cli *DockerCli) CmdCp(args ...string) error {
 	cmd := cli.Subcmd("cp", "CONTAINER:PATH HOSTDIR|-", "Copy files/folders from a PATH on the container to a HOSTDIR on the host\nrunning the command. Use '-' to write the data\nas a tar file to STDOUT.", true)
 	cmd.Require(flag.Exact, 2)
diff --git a/api/client/create.go b/api/client/create.go
index 1adf43b9e7..10b16da8d4 100644
--- a/api/client/create.go
+++ b/api/client/create.go
@@ -128,6 +128,9 @@ func (cli *DockerCli) createContainer(config *runconfig.Config, hostConfig *runc
 	return &response, nil
 }
 
+// CmdCreate creates a new container from a given image.
+//
+// Usage: docker create [OPTIONS] IMAGE [COMMAND] [ARG...]
 func (cli *DockerCli) CmdCreate(args ...string) error {
 	cmd := cli.Subcmd("create", "IMAGE [COMMAND] [ARG...]", "Create a new container", true)
 
diff --git a/api/client/diff.go b/api/client/diff.go
index f82e9c1b2f..08f16a7123 100644
--- a/api/client/diff.go
+++ b/api/client/diff.go
@@ -9,6 +9,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdDiff shows changes on a container's filesystem.
+//
+// Each changed file is printed on a separate line, prefixed with a single character that indicates the status of the file: C (modified), A (added), or D (deleted).
+//
+// Usage: docker diff CONTAINER
 func (cli *DockerCli) CmdDiff(args ...string) error {
 	cmd := cli.Subcmd("diff", "CONTAINER", "Inspect changes on a container's filesystem", true)
 	cmd.Require(flag.Exact, 1)
diff --git a/api/client/events.go b/api/client/events.go
index bc39e3cfd0..047c5559b9 100644
--- a/api/client/events.go
+++ b/api/client/events.go
@@ -12,6 +12,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdEvents prints a live stream of real time events from the server.
+//
+// Usage: docker events [OPTIONS]
 func (cli *DockerCli) CmdEvents(args ...string) error {
 	cmd := cli.Subcmd("events", "", "Get real time events from the server", true)
 	since := cmd.String([]string{"#since", "-since"}, "", "Show all events created since timestamp")
diff --git a/api/client/exec.go b/api/client/exec.go
index 8ededebd12..51acb3710d 100644
--- a/api/client/exec.go
+++ b/api/client/exec.go
@@ -12,6 +12,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdExec runs a command in a running container.
+//
+// Usage: docker exec [OPTIONS] CONTAINER COMMAND [ARG...]
 func (cli *DockerCli) CmdExec(args ...string) error {
 	cmd := cli.Subcmd("exec", "CONTAINER COMMAND [ARG...]", "Run a command in a running container", true)
 
diff --git a/api/client/export.go b/api/client/export.go
index 5b13b0a253..dab83490e5 100644
--- a/api/client/export.go
+++ b/api/client/export.go
@@ -10,6 +10,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdExport exports a filesystem as a tar archive.
+//
+// The tar archive is streamed to STDOUT by default or written to a file.
+//
+// Usage: docker export [OPTIONS] CONTAINER
 func (cli *DockerCli) CmdExport(args ...string) error {
 	cmd := cli.Subcmd("export", "CONTAINER", "Export a filesystem as a tar archive (streamed to STDOUT by default)", true)
 	outfile := cmd.String([]string{"o", "-output"}, "", "Write to a file, instead of STDOUT")
diff --git a/api/client/help.go b/api/client/help.go
index 5dea652b08..2f2d50bbf2 100644
--- a/api/client/help.go
+++ b/api/client/help.go
@@ -7,6 +7,11 @@ import (
 	flag "github.com/docker/docker/pkg/mflag"
 )
 
+// CmdHelp displays information on a Docker command.
+//
+//If more than one command is specified, information is only shown for the first command.
+//
+// Usage: docker help COMMAND or docker COMMAND --help
 func (cli *DockerCli) CmdHelp(args ...string) error {
 	if len(args) > 1 {
 		method, exists := cli.getMethod(args[:2]...)
diff --git a/api/client/history.go b/api/client/history.go
index 98ba68f9a0..b932a4eda4 100644
--- a/api/client/history.go
+++ b/api/client/history.go
@@ -12,6 +12,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdHistory shows the history of an image.
+//
+// Usage: docker history [OPTIONS] IMAGE
 func (cli *DockerCli) CmdHistory(args ...string) error {
 	cmd := cli.Subcmd("history", "IMAGE", "Show the history of an image", true)
 	quiet := cmd.Bool([]string{"q", "-quiet"}, false, "Only show numeric IDs")
diff --git a/api/client/images.go b/api/client/images.go
index d59a0838aa..1b2dd0cd5a 100644
--- a/api/client/images.go
+++ b/api/client/images.go
@@ -85,6 +85,9 @@ func (cli *DockerCli) printTreeNode(noTrunc bool, image *engine.Env, prefix stri
 	}
 }
 
+// CmdImages lists the images in a specified repository, or all top-level images if no repository is specified.
+//
+// Usage: docker images [OPTIONS] [REPOSITORY]
 func (cli *DockerCli) CmdImages(args ...string) error {
 	cmd := cli.Subcmd("images", "[REPOSITORY]", "List images", true)
 	quiet := cmd.Bool([]string{"q", "-quiet"}, false, "Only show numeric IDs")
diff --git a/api/client/import.go b/api/client/import.go
index be8e8a6e73..4264e1c288 100644
--- a/api/client/import.go
+++ b/api/client/import.go
@@ -12,6 +12,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdImport creates an empty filesystem image, imports the contents of the tarball into the image, and optionally tags the image.
+//
+// The URL argument is the address of a tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) file. If the URL is '-', then the tar file is read from STDIN.
+//
+// Usage: docker import [OPTIONS] URL [REPOSITORY[:TAG]]
 func (cli *DockerCli) CmdImport(args ...string) error {
 	cmd := cli.Subcmd("import", "URL|- [REPOSITORY[:TAG]]", "Create an empty filesystem image and import the contents of the\ntarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) into it, then\noptionally tag it.", true)
 	flChanges := opts.NewListOpts(nil)
diff --git a/api/client/info.go b/api/client/info.go
index 795847f59c..96ddeadefc 100644
--- a/api/client/info.go
+++ b/api/client/info.go
@@ -12,7 +12,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker info': display system-wide information.
+// CmdInfo displays system-wide information.
+//
+// Usage: docker info
 func (cli *DockerCli) CmdInfo(args ...string) error {
 	cmd := cli.Subcmd("info", "", "Display system-wide information", true)
 	cmd.Require(flag.Exact, 0)
diff --git a/api/client/inspect.go b/api/client/inspect.go
index f63858981e..2a840c4bcd 100644
--- a/api/client/inspect.go
+++ b/api/client/inspect.go
@@ -12,6 +12,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdInspect displays low-level information on one or more containers or images.
+//
+// Usage: docker inspect [OPTIONS] CONTAINER|IMAGE [CONTAINER|IMAGE...]
 func (cli *DockerCli) CmdInspect(args ...string) error {
 	cmd := cli.Subcmd("inspect", "CONTAINER|IMAGE [CONTAINER|IMAGE...]", "Return low-level information on a container or image", true)
 	tmplStr := cmd.String([]string{"f", "#format", "-format"}, "", "Format the output using the given go template")
diff --git a/api/client/kill.go b/api/client/kill.go
index 1b8e27d356..0f4536fee9 100644
--- a/api/client/kill.go
+++ b/api/client/kill.go
@@ -7,7 +7,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker kill NAME' kills a running container
+// CmdKill kills one or more running container using SIGKILL or a specified signal.
+//
+// Usage: docker kill [OPTIONS] CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdKill(args ...string) error {
 	cmd := cli.Subcmd("kill", "CONTAINER [CONTAINER...]", "Kill a running container using SIGKILL or a specified signal", true)
 	signal := cmd.String([]string{"s", "-signal"}, "KILL", "Signal to send to the container")
diff --git a/api/client/load.go b/api/client/load.go
index 25ef0ab6ce..e8eb8e251d 100644
--- a/api/client/load.go
+++ b/api/client/load.go
@@ -8,6 +8,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdLoad loads an image from a tar archive.
+//
+// The tar archive is read from STDIN by default, or from a tar archive file.
+//
+// Usage: docker load [OPTIONS]
 func (cli *DockerCli) CmdLoad(args ...string) error {
 	cmd := cli.Subcmd("load", "", "Load an image from a tar archive on STDIN", true)
 	infile := cmd.String([]string{"i", "-input"}, "", "Read from a tar archive file, instead of STDIN")
diff --git a/api/client/login.go b/api/client/login.go
index 97311d0581..6fe2daba87 100644
--- a/api/client/login.go
+++ b/api/client/login.go
@@ -17,7 +17,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker login': login / register a user to registry service.
+// CmdLogin logs in or registers a user to a Docker registry service.
+//
+// If no server is specified, the user will be logged into or registered to the registry's index server.
+//
+// Usage: docker login SERVER
 func (cli *DockerCli) CmdLogin(args ...string) error {
 	cmd := cli.Subcmd("login", "[SERVER]", "Register or log in to a Docker registry server, if no server is\nspecified \""+registry.IndexServerAddress()+"\" is the default.", true)
 	cmd.Require(flag.Max, 1)
diff --git a/api/client/logout.go b/api/client/logout.go
index bd135de7f1..5d9a77f2c3 100644
--- a/api/client/logout.go
+++ b/api/client/logout.go
@@ -8,7 +8,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker logout': log out a user from a registry service.
+// CmdLogout logs a user out from a Docker registry.
+//
+// If no server is specified, the user will be logged out from the registry's index server.
+//
+// Usage: docker logout [SERVER]
 func (cli *DockerCli) CmdLogout(args ...string) error {
 	cmd := cli.Subcmd("logout", "[SERVER]", "Log out from a Docker registry, if no server is\nspecified \""+registry.IndexServerAddress()+"\" is the default.", true)
 	cmd.Require(flag.Max, 1)
diff --git a/api/client/logs.go b/api/client/logs.go
index 1cb580052e..11809d572d 100644
--- a/api/client/logs.go
+++ b/api/client/logs.go
@@ -9,6 +9,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdLogs fetches the logs of a given container.
+//
+// docker logs [OPTIONS] CONTAINER
 func (cli *DockerCli) CmdLogs(args ...string) error {
 	var (
 		cmd    = cli.Subcmd("logs", "CONTAINER", "Fetch the logs of a container", true)
diff --git a/api/client/pause.go b/api/client/pause.go
index db85368a96..a13be5c111 100644
--- a/api/client/pause.go
+++ b/api/client/pause.go
@@ -7,6 +7,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdPause pauses all processes within one or more containers.
+//
+// Usage: docker pause CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdPause(args ...string) error {
 	cmd := cli.Subcmd("pause", "CONTAINER [CONTAINER...]", "Pause all processes within a container", true)
 	cmd.Require(flag.Min, 1)
diff --git a/api/client/port.go b/api/client/port.go
index 713fc8b965..cc3da8afe6 100644
--- a/api/client/port.go
+++ b/api/client/port.go
@@ -10,6 +10,10 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdPort lists port mappings for a container.
+// If a private port is specified, it also shows the public-facing port that is NATed to the private port.
+//
+// Usage: docker port CONTAINER [PRIVATE_PORT[/PROTO]]
 func (cli *DockerCli) CmdPort(args ...string) error {
 	cmd := cli.Subcmd("port", "CONTAINER [PRIVATE_PORT[/PROTO]]", "List port mappings for the CONTAINER, or lookup the public-facing port that\nis NAT-ed to the PRIVATE_PORT", true)
 	cmd.Require(flag.Min, 1)
diff --git a/api/client/ps.go b/api/client/ps.go
index fa9b2b4882..28891c9842 100644
--- a/api/client/ps.go
+++ b/api/client/ps.go
@@ -18,6 +18,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdPs outputs a list of Docker containers.
+//
+// Usage: docker ps [OPTIONS]
 func (cli *DockerCli) CmdPs(args ...string) error {
 	var (
 		err error
diff --git a/api/client/pull.go b/api/client/pull.go
index a27c7cb960..3f42ba2ced 100644
--- a/api/client/pull.go
+++ b/api/client/pull.go
@@ -14,6 +14,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdPull pulls an image or a repository from the registry.
+//
+// Usage: docker pull [OPTIONS] IMAGENAME[:TAG|@DIGEST]
 func (cli *DockerCli) CmdPull(args ...string) error {
 	cmd := cli.Subcmd("pull", "NAME[:TAG|@DIGEST]", "Pull an image or a repository from the registry", true)
 	allTags := cmd.Bool([]string{"a", "-all-tags"}, false, "Download all tagged images in the repository")
diff --git a/api/client/push.go b/api/client/push.go
index 92a87ed270..025cf682c6 100644
--- a/api/client/push.go
+++ b/api/client/push.go
@@ -13,6 +13,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdPush pushes an image or repository to the registry.
+//
+// Usage: docker push NAME[:TAG]
 func (cli *DockerCli) CmdPush(args ...string) error {
 	cmd := cli.Subcmd("push", "NAME[:TAG]", "Push an image or a repository to the registry", true)
 	cmd.Require(flag.Exact, 1)
diff --git a/api/client/rename.go b/api/client/rename.go
index 82d2b74c32..45cf43595f 100644
--- a/api/client/rename.go
+++ b/api/client/rename.go
@@ -2,6 +2,9 @@ package client
 
 import "fmt"
 
+// CmdRename renames a container.
+//
+// Usage: docker rename OLD_NAME NEW_NAME
 func (cli *DockerCli) CmdRename(args ...string) error {
 	cmd := cli.Subcmd("rename", "OLD_NAME NEW_NAME", "Rename a container", true)
 	if err := cmd.Parse(args); err != nil {
diff --git a/api/client/restart.go b/api/client/restart.go
index 90c5b3fab1..84882f2920 100644
--- a/api/client/restart.go
+++ b/api/client/restart.go
@@ -9,6 +9,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdRestart restarts one or more running containers.
+//
+// Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdRestart(args ...string) error {
 	cmd := cli.Subcmd("restart", "CONTAINER [CONTAINER...]", "Restart a running container", true)
 	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing the container")
diff --git a/api/client/rmi.go b/api/client/rmi.go
index 7c5b4d0aff..93e41654b9 100644
--- a/api/client/rmi.go
+++ b/api/client/rmi.go
@@ -9,7 +9,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker rmi IMAGE' removes all images with the name IMAGE
+// CmdRmi removes all images with the specified name(s).
+//
+// Usage: docker rmi [OPTIONS] IMAGE [IMAGE...]
 func (cli *DockerCli) CmdRmi(args ...string) error {
 	var (
 		cmd     = cli.Subcmd("rmi", "IMAGE [IMAGE...]", "Remove one or more images", true)
diff --git a/api/client/run.go b/api/client/run.go
index e00a3d78db..1c37e40dd3 100644
--- a/api/client/run.go
+++ b/api/client/run.go
@@ -35,6 +35,9 @@ func (cid *cidFile) Write(id string) error {
 	return nil
 }
 
+// CmdRun runs a command in a new container.
+//
+// Usage: docker run [OPTIONS] IMAGE [COMMAND] [ARG...]
 func (cli *DockerCli) CmdRun(args ...string) error {
 	// FIXME: just use runconfig.Parse already
 	cmd := cli.Subcmd("run", "IMAGE [COMMAND] [ARG...]", "Run a command in a new container", true)
diff --git a/api/client/save.go b/api/client/save.go
index 8d42218d88..e0cdd1c294 100644
--- a/api/client/save.go
+++ b/api/client/save.go
@@ -10,6 +10,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdSave saves one or more images to a tar archive.
+//
+// The tar archive is written to STDOUT by default, or written to a file.
+//
+// Usage: docker save [OPTIONS] IMAGE [IMAGE...]
 func (cli *DockerCli) CmdSave(args ...string) error {
 	cmd := cli.Subcmd("save", "IMAGE [IMAGE...]", "Save an image(s) to a tar archive (streamed to STDOUT by default)", true)
 	outfile := cmd.String([]string{"o", "-output"}, "", "Write to an file, instead of STDOUT")
diff --git a/api/client/search.go b/api/client/search.go
index 1b43ac9910..21d7048418 100644
--- a/api/client/search.go
+++ b/api/client/search.go
@@ -11,6 +11,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdSearch searches the Docker Hub for images.
+//
+// Usage: docker search [OPTIONS] TERM
 func (cli *DockerCli) CmdSearch(args ...string) error {
 	cmd := cli.Subcmd("search", "TERM", "Search the Docker Hub for images", true)
 	noTrunc := cmd.Bool([]string{"#notrunc", "-no-trunc"}, false, "Don't truncate output")
diff --git a/api/client/start.go b/api/client/start.go
index 8d4ea6bb9d..ef8f17bd4e 100644
--- a/api/client/start.go
+++ b/api/client/start.go
@@ -40,6 +40,9 @@ func (cli *DockerCli) forwardAllSignals(cid string) chan os.Signal {
 	return sigc
 }
 
+// CmdStart starts one or more stopped containers.
+//
+// Usage: docker start [OPTIONS] CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdStart(args ...string) error {
 	var (
 		cErr chan error
diff --git a/api/client/stats.go b/api/client/stats.go
index 8999abdb2b..bdb8ec4b8a 100644
--- a/api/client/stats.go
+++ b/api/client/stats.go
@@ -106,6 +106,11 @@ func (s *containerStats) Display(w io.Writer) error {
 	return nil
 }
 
+// CmdStats displays a live stream of resource usage statistics for one or more containers.
+//
+// This shows real-time information on CPU usage, memory usage, and network I/O.
+//
+// Usage: docker stats CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdStats(args ...string) error {
 	cmd := cli.Subcmd("stats", "CONTAINER [CONTAINER...]", "Display a live stream of one or more containers' resource usage statistics", true)
 	cmd.Require(flag.Min, 1)
diff --git a/api/client/stop.go b/api/client/stop.go
index aa46a2fea7..943f8c58ad 100644
--- a/api/client/stop.go
+++ b/api/client/stop.go
@@ -9,6 +9,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdStop stops one or more running containers.
+//
+// A running container is stopped by first sending SIGTERM and then SIGKILL if the container fails to stop within a grace period (the default is 10 seconds).
+//
+// Usage: docker stop [OPTIONS] CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdStop(args ...string) error {
 	cmd := cli.Subcmd("stop", "CONTAINER [CONTAINER...]", "Stop a running container by sending SIGTERM and then SIGKILL after a\ngrace period", true)
 	nSeconds := cmd.Int([]string{"t", "-time"}, 10, "Seconds to wait for stop before killing it")
diff --git a/api/client/tag.go b/api/client/tag.go
index 701e381e97..44a32508fb 100644
--- a/api/client/tag.go
+++ b/api/client/tag.go
@@ -9,6 +9,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdTag tags an image into a repository.
+//
+// Usage: docker tag [OPTIONS] IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]
 func (cli *DockerCli) CmdTag(args ...string) error {
 	cmd := cli.Subcmd("tag", "IMAGE[:TAG] [REGISTRYHOST/][USERNAME/]NAME[:TAG]", "Tag an image into a repository", true)
 	force := cmd.Bool([]string{"f", "#force", "-force"}, false, "Force")
diff --git a/api/client/top.go b/api/client/top.go
index 8f8837a9a0..b5129acb9d 100644
--- a/api/client/top.go
+++ b/api/client/top.go
@@ -11,6 +11,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdTop displays the running processes of a container.
+//
+// Usage: docker top CONTAINER
 func (cli *DockerCli) CmdTop(args ...string) error {
 	cmd := cli.Subcmd("top", "CONTAINER [ps OPTIONS]", "Display the running processes of a container", true)
 	cmd.Require(flag.Min, 1)
diff --git a/api/client/unpause.go b/api/client/unpause.go
index c40948404d..c5a66f61b4 100644
--- a/api/client/unpause.go
+++ b/api/client/unpause.go
@@ -7,6 +7,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
+// CmdUnpause unpauses all processes within a container, for one or more containers.
+//
+// Usage: docker unpause CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdUnpause(args ...string) error {
 	cmd := cli.Subcmd("unpause", "CONTAINER [CONTAINER...]", "Unpause all processes within a container", true)
 	cmd.Require(flag.Min, 1)
diff --git a/api/client/version.go b/api/client/version.go
index fa996e5387..d3752d34ef 100644
--- a/api/client/version.go
+++ b/api/client/version.go
@@ -12,7 +12,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker version': show version information
+// CmdVersion shows Docker version information.
+//
+// Available version information is shown for: client Docker version, client API version, client Go version, client Git commit, client OS/Arch, server Docker version, server API version, server Go version, server Git commit, and server OS/Arch.
+//
+// Usage: docker version
 func (cli *DockerCli) CmdVersion(args ...string) error {
 	cmd := cli.Subcmd("version", "", "Show the Docker version information.", true)
 	cmd.Require(flag.Exact, 0)
diff --git a/api/client/wait.go b/api/client/wait.go
index ca9f713aa8..92c3b05dcb 100644
--- a/api/client/wait.go
+++ b/api/client/wait.go
@@ -7,7 +7,11 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// 'docker wait': block until a container stops
+// CmdWait blocks until a container stops, then prints its exit code.
+//
+// If more than one container is specified, this will wait synchronously on each container.
+//
+// Usage: docker wait CONTAINER [CONTAINER...]
 func (cli *DockerCli) CmdWait(args ...string) error {
 	cmd := cli.Subcmd("wait", "CONTAINER [CONTAINER...]", "Block until a container stops, then print its exit code.", true)
 	cmd.Require(flag.Min, 1)

From 2a5a402c717fa0ff05b7e57e85bf3388ba1ee1a5 Mon Sep 17 00:00:00 2001
From: Peggy Li <peggyli.224@gmail.com>
Date: Wed, 25 Mar 2015 16:26:28 -0700
Subject: [PATCH 2/2] Update CmdCommit docstring and fix CmdHelp whitespace

Signed-off-by: Peggy Li <peggyli.224@gmail.com>
---
 api/client/commit.go | 4 ++--
 api/client/help.go   | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/api/client/commit.go b/api/client/commit.go
index 4500f3b424..4214cffce5 100644
--- a/api/client/commit.go
+++ b/api/client/commit.go
@@ -14,9 +14,9 @@ import (
 	"github.com/docker/docker/utils"
 )
 
-// CmdAttach attaches to a running container.
+// CmdCommit creates a new image from a container's changes.
 //
-// Usage: docker attach [OPTIONS] CONTAINER
+// Usage: docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]
 func (cli *DockerCli) CmdCommit(args ...string) error {
 	cmd := cli.Subcmd("commit", "CONTAINER [REPOSITORY[:TAG]]", "Create a new image from a container's changes", true)
 	flPause := cmd.Bool([]string{"p", "-pause"}, true, "Pause container during commit")
diff --git a/api/client/help.go b/api/client/help.go
index 2f2d50bbf2..e95387967a 100644
--- a/api/client/help.go
+++ b/api/client/help.go
@@ -9,7 +9,7 @@ import (
 
 // CmdHelp displays information on a Docker command.
 //
-//If more than one command is specified, information is only shown for the first command.
+// If more than one command is specified, information is only shown for the first command.
 //
 // Usage: docker help COMMAND or docker COMMAND --help
 func (cli *DockerCli) CmdHelp(args ...string) error {