format (GoDoc) comments with Go 1.19 to prepare for go updates

Older versions of Go do not format these comments, so we can already
reformat them ahead of time to prevent gofmt linting failing once
we update to Go 1.19 or up.

Result of:

    gofmt -s -w $(find . -type f -name '*.go' | grep -v "/vendor/")

With some manual adjusting.

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

cli/command/container/cp.go

@@ -368,9 +368,11 @@ func copyToContainer(ctx context.Context, dockerCli command.Cli, copyConfig cpCo
 // in a valid LOCALPATH, like `file:name.txt`. We can resolve this ambiguity by
 // requiring a LOCALPATH with a `:` to be made explicit with a relative or
 // absolute path:
+//
 //	`/path/to/file:name.txt` or `./file:name.txt`
 //
 // This is apparently how `scp` handles this as well:
+//
 //	http://www.cyberciti.biz/faq/rsync-scp-file-name-with-colon-punctuation-in-it/
 //
 // We can't simply check for a filepath separator because container names may

cli/command/container/opts.go

@@ -311,6 +311,7 @@ type containerConfig struct {
 // parse parses the args for the specified command and generates a Config,
 // a HostConfig and returns them with the specified command.
 // If the specified args are not valid, it will return an error.
+//
 //nolint:gocyclo
 func parse(flags *pflag.FlagSet, copts *containerOptions, serverOS string) (*containerConfig, error) {
 	var (
@@ -965,6 +966,7 @@ func parseWindowsDevice(device string) (container.DeviceMapping, error) {
 
 // validateDeviceCgroupRule validates a device cgroup rule string format
 // It will make sure 'val' is in the form:
+//
 //	'type major:minor mode'
 func validateDeviceCgroupRule(val string) (string, error) {
 	if deviceCgroupRuleRegexp.MatchString(val) {
@@ -1009,7 +1011,9 @@ func validateDevice(val string, serverOS string) (string, error) {
 // validateLinuxPath is the implementation of validateDevice knowing that the
 // target server operating system is a Linux daemon.
 // It will make sure 'val' is in the form:
+//
 //	[host-dir:]container-path[:mode]
+//
 // It also validates the device mode.
 func validateLinuxPath(val string, validator func(string) bool) (string, error) {
 	var containerPath string

cli/command/container/start.go

@@ -67,6 +67,7 @@ func NewStartCommand(dockerCli command.Cli) *cobra.Command {
 }
 
 // RunStart executes a `start` command
+//
 //nolint:gocyclo
 func RunStart(dockerCli command.Cli, opts *StartOptions) error {
 	ctx, cancelFun := context.WithCancel(context.Background())

cli/command/container/stats.go

@@ -56,6 +56,7 @@ func NewStatsCommand(dockerCli command.Cli) *cobra.Command {
 
 // runStats 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.
+//
 //nolint:gocyclo
 func runStats(dockerCli command.Cli, opts *statsOptions) error {
 	showAll := len(opts.containers) == 0

cli/command/formatter/tabwriter/tabwriter.go

@@ -11,7 +11,8 @@
 // The text/tabwriter package is frozen and is not accepting new features.
 
 // based on https://github.com/golang/go/blob/master/src/text/tabwriter/tabwriter.go Last modified 690ac40 on 31 Jan
-//nolint
+
+//nolint:gocyclo,nakedret,revive,unused // ignore linting errors, so that we can stick close to upstream
 package tabwriter
 
 import (

cli/command/image/trust.go

@@ -42,6 +42,7 @@ func TrustedPush(ctx context.Context, cli command.Cli, repoInfo *registry.Reposi
 }
 
 // PushTrustedReference pushes a canonical reference to the trust server.
+//
 //nolint:gocyclo
 func PushTrustedReference(streams command.Streams, repoInfo *registry.RepositoryInfo, ref reference.Named, authConfig types.AuthConfig, in io.Reader) error {
 	// If it is a trusted push we would like to find the target entry which match the

cli/command/network/create.go

@@ -130,6 +130,7 @@ func runCreate(dockerCli command.Cli, options createOptions) error {
 // possible to correlate the various related parameters and consolidate them.
 // consolidateIpam consolidates subnets, ip-ranges, gateways and auxiliary addresses into
 // structured ipam data.
+//
 //nolint:gocyclo
 func consolidateIpam(subnets, ranges, gateways []string, auxaddrs map[string]string) ([]network.IPAMConfig, error) {
 	if len(subnets) < len(ranges) || len(subnets) < len(gateways) {

cli/command/service/list.go

@@ -109,6 +109,7 @@ func runList(dockerCli command.Cli, opts listOptions) error {
 // there may be other situations where the client uses the "default" version.
 // To take these situations into account, we do a quick check for services
 // that don't have ServiceStatus set, and perform a lookup for those.
+//
 //nolint:gocyclo
 func AppendServiceStatus(ctx context.Context, c client.APIClient, services []swarm.Service) ([]swarm.Service, error) {
 	status := map[string]*swarm.ServiceStatus{}

cli/command/service/opts.go

@@ -466,9 +466,13 @@ func (opts *healthCheckOptions) toHealthConfig() (*container.HealthConfig, error
 }
 
 // convertExtraHostsToSwarmHosts converts an array of extra hosts in cli
+//
 //	<host>:<ip>
+//
 // into a swarmkit host format:
+//
 //	IP_address canonical_hostname [aliases...]
+//
 // This assumes input value (<host>:<ip>) has already been validated
 func convertExtraHostsToSwarmHosts(extraHosts []string) []string {
 	hosts := []string{}

cli/command/service/progress/progress.go

@@ -68,6 +68,7 @@ func terminalState(state swarm.TaskState) bool {
 }
 
 // ServiceProgress outputs progress information for convergence of a service.
+//
 //nolint:gocyclo
 func ServiceProgress(ctx context.Context, client client.APIClient, serviceID string, progressWriter io.WriteCloser) error {
 	defer progressWriter.Close()

cli/command/service/update.go

@@ -1421,23 +1421,22 @@ func updateCredSpecConfig(flags *pflag.FlagSet, containerSpec *swarm.ContainerSp
 // In other words, given a service with the following:
 //
 // | CapDrop        | CapAdd        |
-// | -------------- | ------------- |
+// |----------------|---------------|
 // | CAP_SOME_CAP   |               |
 //
 // When updating the service, and applying `--cap-add CAP_SOME_CAP`, the previously
 // dropped capability is removed:
 //
 // | CapDrop        | CapAdd        |
-// | -------------- | ------------- |
+// |----------------|---------------|
 // |                |               |
 //
 // After updating the service a second time, applying `--cap-add CAP_SOME_CAP`,
 // capability is now added:
 //
 // | CapDrop        | CapAdd        |
-// | -------------- | ------------- |
+// |----------------|---------------|
 // |                | CAP_SOME_CAP  |
-//
 func updateCapabilities(flags *pflag.FlagSet, containerSpec *swarm.ContainerSpec) {
 	var (
 		toAdd, toDrop map[string]bool

cli/command/service/update_test.go

@@ -520,8 +520,9 @@ func (s secretAPIClientMock) SecretUpdate(ctx context.Context, id string, versio
 	return nil
 }
 
-// TestUpdateSecretUpdateInPlace tests the ability to update the "target" of an secret with "docker service update"
-// by combining "--secret-rm" and "--secret-add" for the same secret.
+// TestUpdateSecretUpdateInPlace tests the ability to update the "target" of a
+// secret with "docker service update" by combining "--secret-rm" and
+// "--secret-add" for the same secret.
 func TestUpdateSecretUpdateInPlace(t *testing.T) {
 	apiClient := secretAPIClientMock{
 		listResult: []swarm.Secret{

cli/compose/loader/windows_path.go

@@ -28,6 +28,7 @@ func isAbs(path string) (b bool) {
 
 // volumeNameLen returns length of the leading volume name on Windows.
 // It returns 0 elsewhere.
+//
 //nolint:gocyclo
 func volumeNameLen(path string) int {
 	if len(path) < 2 {

cli/context/store/doc.go

@@ -1,20 +1,32 @@
-// Package store provides a generic way to store credentials to connect to virtually any kind of remote system.
-// The term `context` comes from the similar feature in Kubernetes kubectl config files.
+// Package store provides a generic way to store credentials to connect to
+// virtually any kind of remote system.
+// The term `context` comes from the similar feature in Kubernetes kubectl
+// config files.
 //
-// Conceptually, a context is a set of metadata and TLS data, that can be used to connect to various endpoints
-// of a remote system. TLS data and metadata are stored separately, so that in the future, we will be able to store sensitive
-// information in a more secure way, depending on the os we are running on (e.g.: on Windows we could use the user Certificate Store, on Mac OS the user Keychain...).
+// Conceptually, a context is a set of metadata and TLS data, that can be used
+// to connect to various endpoints of a remote system. TLS data and metadata
+// are stored separately, so that in the future, we will be able to store
+// sensitive information in a more secure way, depending on the os we are running
+// on (e.g.: on Windows we could use the user Certificate Store, on macOS the
+// user Keychain...).
 //
 // Current implementation is purely file based with the following structure:
+//
 //	${CONTEXT_ROOT}
-//   - meta/
-//     - <context id>/meta.json: contains context medata (key/value pairs) as well as a list of endpoints (themselves containing key/value pair metadata)
-//   - tls/
-//     - <context id>/endpoint1/: directory containing TLS data for the endpoint1 in the corresponding context
+//	  meta/
+//	    <context id>/meta.json: contains context medata (key/value pairs) as
+//	                            well as a list of endpoints (themselves containing
+//	                            key/value pair metadata).
+//	  tls/
+//	    <context id>/endpoint1/: directory containing TLS data for the endpoint1
+//	                             in the corresponding context.
 //
-// The context store itself has absolutely no knowledge about what a docker endpoint should contain in term of metadata or TLS config.
-// Client code is responsible for generating and parsing endpoint metadata and TLS files.
-// The multi-endpoints approach of this package allows to combine many different endpoints in the same "context".
+// The context store itself has absolutely no knowledge about what a docker
+// endpoint should contain in term of metadata or TLS config. Client code is
+// responsible for generating and parsing endpoint metadata and TLS files. The
+// multi-endpoints approach of this package allows to combine many different
+// endpoints in the same "context".
 //
-// Context IDs are actually SHA256 hashes of the context name, and are there only to avoid dealing with special characters in context names.
+// Context IDs are actually SHA256 hashes of the context name, and are there
+// only to avoid dealing with special characters in context names.
 package store

internal/test/builders/doc.go

@@ -1,3 +1,2 @@
 // Package builders helps you create struct for your unit test while keeping them expressive.
-//
 package builders

internal/test/doc.go

@@ -1,5 +1,4 @@
 // Package test is a test-only package that can be used by other cli package to write unit test.
 //
 // It as an internal package and cannot be used outside of github.com/docker/cli package.
-//
 package test

opts/envfile.go

@@ -6,12 +6,12 @@ import (
 
 // ParseEnvFile reads a file with environment variables enumerated by lines
 //
-// ``Environment variable names used by the utilities in the Shell and
+// “Environment variable names used by the utilities in the Shell and
 // Utilities volume of IEEE Std 1003.1-2001 consist solely of uppercase
 // letters, digits, and the '_' (underscore) from the characters defined in
 // Portable Character Set and do not begin with a digit. *But*, other
 // characters may be permitted by an implementation; applications shall
-// tolerate the presence of such names.''
+// tolerate the presence of such names.”
 // -- http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html
 //
 // As of #16585, it's up to application inside docker to validate or not

opts/gpus.go

@@ -24,6 +24,7 @@ func parseCount(s string) (int, error) {
 }
 
 // Set a new mount value
+//
 //nolint:gocyclo
 func (o *GpuOpts) Set(value string) error {
 	csvReader := csv.NewReader(strings.NewReader(value))

opts/mount.go

@@ -18,6 +18,7 @@ type MountOpt struct {
 }
 
 // Set a new mount value
+//
 //nolint:gocyclo
 func (m *MountOpt) Set(value string) error {
 	csvReader := csv.NewReader(strings.NewReader(value))

opts/parse.go

@@ -55,7 +55,9 @@ func ConvertKVStringsToMap(values []string) map[string]string {
 // ConvertKVStringsToMapWithNil converts ["key=value"] to {"key":"value"}
 // but set unset keys to nil - meaning the ones with no "=" in them.
 // We use this in cases where we need to distinguish between
+//
 //	FOO=  and FOO
+//
 // where the latter case just means FOO was mentioned but not given a value
 func ConvertKVStringsToMapWithNil(values []string) map[string]*string {
 	result := make(map[string]*string, len(values))

opts/port.go

@@ -26,6 +26,7 @@ type PortOpt struct {
 }
 
 // Set a new port value
+//
 //nolint:gocyclo
 func (p *PortOpt) Set(value string) error {
 	longSyntax, err := regexp.MatchString(`\w+=\w+(,\w+=\w+)*`, value)