1. docker
  2. Commit 070038bbc720192338850ff714459fbd5e633853
Browse code

Add GoDoc for client package

- Tightened up copy in README
- Make example in README a bit simpler
- Update README to point at GoDoc

Signed-off-by: Ben Firshman <ben@firshman.co.uk>

Ben Firshman authored on 2016/10/08 22:34:37
Showing 2 changed files
client/README.md
History View file @ 070038b
... ... 
@@ -1,37 +1,35 @@
1 
-## Client
1 
+## Go client for the Docker Remote API
2 2
3 
-The client package implements a fully featured http client to interact with the Docker engine. It's modeled after the requirements of the Docker engine CLI, but it can also serve other purposes.
3 
+The `docker` command uses this package to communicate with the daemon. It can also be used by your own Go applications to do anything the command-line interface does – running containers, pulling images, managing swarms, etc.
4 4
5 
-### Usage
6 
-
7 
-You can use this client package in your applications by creating a new client object. Then use that object to execute operations against the remote server. Follow the example below to see how to list all the containers running in a Docker engine host:
5 
+For example, to list running containers (the equivalent of `docker ps`):
8 6
9 7 
 ```go
10 8 
 package main
11 9
12 10 
 import (
13 
-	"fmt"
14 11 
 	"context"
12 
+	"fmt"
15 13
16 
-	"github.com/docker/docker/client"
17 14 
 	"github.com/docker/docker/api/types"
15 
+	"github.com/docker/docker/client"
18 16 
 )
19 17
20 18 
 func main() {
21 
-	defaultHeaders := map[string]string{"User-Agent": "engine-api-cli-1.0"}
22 
-	cli, err := client.NewClient("unix:///var/run/docker.sock", "v1.22", nil, defaultHeaders)
19 
+	cli, err := client.NewEnvClient()
23 20 
 	if err != nil {
24 21 
 		panic(err)
25 22 
 	}
26 23
27 
-	options := types.ContainerListOptions{All: true}
28 
-	containers, err := cli.ContainerList(context.Background(), options)
24 
+	containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
29 25 
 	if err != nil {
30 26 
 		panic(err)
31 27 
 	}
32 28
33 
-	for _, c := range containers {
34 
-		fmt.Println(c.ID)
29 
+	for _, container := range containers {
30 
+		fmt.Printf("%s %s\n", container.ID[:10], container.Image)
35 31 
 	}
36 32 
 }
37 33 
 ```
34 
+
35 
+[Full documentation is available on GoDoc.](https://godoc.org/github.com/docker/docker/client)
client/client.go
History View file @ 070038b
... ... 
@@ -1,3 +1,48 @@
1 
+/*
2 
+Package client is a Go client for the Docker Remote API.
3 
+
4 
+The "docker" command uses this package to communicate with the daemon. It can also
5 
+be used by your own Go applications to do anything the command-line interface does
6 
+– running containers, pulling images, managing swarms, etc.
7 
+
8 
+For more information about the Remote API, see the documentation:
9 
+https://docs.docker.com/engine/reference/api/docker_remote_api/
10 
+
11 
+Usage
12 
+
13 
+You use the library by creating a client object and calling methods on it. The
14 
+client can be created either from environment variables with NewEnvClient, or
15 
+configured manually with NewClient.
16 
+
17 
+For example, to list running containers (the equivalent of "docker ps"):
18 
+
19 
+	package main
20 
+
21 
+	import (
22 
+		"context"
23 
+		"fmt"
24 
+
25 
+		"github.com/docker/docker/api/types"
26 
+		"github.com/docker/docker/client"
27 
+	)
28 
+
29 
+	func main() {
30 
+		cli, err := client.NewEnvClient()
31 
+		if err != nil {
32 
+			panic(err)
33 
+		}
34 
+
35 
+		containers, err := cli.ContainerList(context.Background(), types.ContainerListOptions{})
36 
+		if err != nil {
37 
+			panic(err)
38 
+		}
39 
+
40 
+		for _, container := range containers {
41 
+			fmt.Printf("%s %s\n", container.ID[:10], container.Image)
42 
+		}
43 
+	}
44 
+
45 
+*/
1 46 
 package client
2 47
3 48 
 import (