From 61d084593c815bb2c40dedc3026901023f46b9f9 Mon Sep 17 00:00:00 2001 From: Cory Snider Date: Fri, 31 Mar 2023 16:15:01 -0400 Subject: [PATCH] client: deprecate NewClient properly The 'Deprecated:' line in NewClient's doc comment was not in a new paragraph, so GoDoc, linters, and IDEs were unaware that it was deprecated. The package documentation also continued to reference NewClient. Update the doc comments to finish documenting that NewClient is deprecated. Signed-off-by: Cory Snider (cherry picked from commit 6b9968e8b10268d76725ce187c9ad800c75cd8b8) Signed-off-by: Sebastiaan van Stijn --- client/client.go | 7 ++++--- client/client_deprecated.go | 8 ++++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/client/client.go b/client/client.go index 26a0fa2756..09ea4851ff 100644 --- a/client/client.go +++ b/client/client.go @@ -6,9 +6,10 @@ https://docs.docker.com/engine/api/ # Usage -You use the library by creating a client object and calling methods on it. The -client can be created either from environment variables with NewClientWithOpts(client.FromEnv), -or configured manually with NewClient(). +You use the library by constructing a client object using [NewClientWithOpts] +and calling methods on it. The client can be configured from environment +variables by passing the [FromEnv] option, or configured manually by passing any +of the other available [Opts]. For example, to list running containers (the equivalent of "docker ps"): diff --git a/client/client_deprecated.go b/client/client_deprecated.go index 54cdfc29a8..9e366ce20d 100644 --- a/client/client_deprecated.go +++ b/client/client_deprecated.go @@ -9,7 +9,11 @@ import "net/http" // It won't send any version information if the version number is empty. It is // highly recommended that you set a version or your client may break if the // server is upgraded. -// Deprecated: use NewClientWithOpts +// +// Deprecated: use [NewClientWithOpts] passing the [WithHost], [WithVersion], +// [WithHTTPClient] and [WithHTTPHeaders] options. We recommend enabling API +// version negotiation by passing the [WithAPIVersionNegotiation] option instead +// of WithVersion. func NewClient(host string, version string, client *http.Client, httpHeaders map[string]string) (*Client, error) { return NewClientWithOpts(WithHost(host), WithVersion(version), WithHTTPClient(client), WithHTTPHeaders(httpHeaders)) } @@ -17,7 +21,7 @@ func NewClient(host string, version string, client *http.Client, httpHeaders map // NewEnvClient initializes a new API client based on environment variables. // See FromEnv for a list of support environment variables. // -// Deprecated: use NewClientWithOpts(FromEnv) +// Deprecated: use [NewClientWithOpts] passing the [FromEnv] option. func NewEnvClient() (*Client, error) { return NewClientWithOpts(FromEnv) }