client: improve GoDoc, and minor touch-ups

- Improve documentation of various functions to better describe their behavior.
- Rename some variables to be more descriptive (as this is client code, used
  by external consumers, it's nice to be a bit more explicit).
- Remove a redundant check in `WithVersionFromEnv()`, as `WithVersion()`
  already checks for empty values.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

1 files changed, 22 insertions, 14 deletions

diff --git a/client/options.go b/client/options.go
index 77a9abc141..028f61c00a 100644
--- a/client/options.go
+++ b/client/options.go
@@ -18,11 +18,18 @@ type Opt func(*Client) error
 
 // FromEnv configures the client with values from environment variables.
 //
-// Supported environment variables:
-// DOCKER_HOST to set the url to the docker server.
-// DOCKER_API_VERSION to set the version of the API to reach, leave empty for latest.
-// DOCKER_CERT_PATH to load the TLS certificates from.
-// DOCKER_TLS_VERIFY to enable or disable TLS verification, off by default.
+// FromEnv uses the following environment variables:
+//
+// DOCKER_HOST to set the URL to the docker server.
+//
+// DOCKER_API_VERSION to set the version of the API to
+// use, leave empty for latest.
+//
+// DOCKER_CERT_PATH to specify the directory from which to
+// load the TLS certificates (ca.pem, cert.pem, key.pem).
+//
+// DOCKER_TLS_VERIFY to enable or disable TLS verification (off by
+// default).
 func FromEnv(c *Client) error {
 	ops := []Opt{
 		WithTLSClientConfigFromEnv(),
@@ -75,8 +82,8 @@ func WithHost(host string) Opt {
 }
 
 // WithHostFromEnv overrides the client host with the host specified in the
-// DOCKER_HOST environment variable. If DOCKER_HOST is not set, the host is
-// not modified.
+// DOCKER_HOST environment variable. If DOCKER_HOST is not set,
+// or set to an empty value, the host is not modified.
 func WithHostFromEnv() Opt {
 	return func(c *Client) error {
 		if host := os.Getenv("DOCKER_HOST"); host != "" {
@@ -145,9 +152,13 @@ func WithTLSClientConfig(cacertPath, certPath, keyPath string) Opt {
 // settings in the DOCKER_CERT_PATH and DOCKER_TLS_VERIFY environment variables.
 // If DOCKER_CERT_PATH is not set or empty, TLS configuration is not modified.
 //
-// Supported environment variables:
-// DOCKER_CERT_PATH  directory to load the TLS certificates (ca.pem, cert.pem, key.pem) from.
-// DOCKER_TLS_VERIFY to enable or disable TLS verification, off by default.
+// WithTLSClientConfigFromEnv uses the following environment variables:
+//
+// DOCKER_CERT_PATH to specify the directory from which to
+// load the TLS certificates (ca.pem, cert.pem, key.pem).
+//
+// DOCKER_TLS_VERIFY to enable or disable TLS verification (off by
+// default).
 func WithTLSClientConfigFromEnv() Opt {
 	return func(c *Client) error {
 		dockerCertPath := os.Getenv("DOCKER_CERT_PATH")
@@ -190,10 +201,7 @@ func WithVersion(version string) Opt {
 // the version is not modified.
 func WithVersionFromEnv() Opt {
 	return func(c *Client) error {
-		if version := os.Getenv("DOCKER_API_VERSION"); version != "" {
-			return WithVersion(version)(c)
-		}
-		return nil
+		return WithVersion(os.Getenv("DOCKER_API_VERSION"))(c)
 	}
 }