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 <csnider@mirantis.com>
(cherry picked from commit 6b9968e8b10268d76725ce187c9ad800c75cd8b8)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

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"):
 

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)
 }