build: Use Go 1.19

Go 1.19's "fmt" has some awareness of the new doc comment formatting
conventions and adjusts the presentation of the source comments to make
it clearer how godoc would interpret them. Therefore this commit includes
various updates made by "go fmt" to acheve that.

In line with our usual convention that we make stylistic/grammar/spelling
tweaks typically only when we're "in the area" changing something else
anyway, I also took this opportunity to review most of the comments that
this updated to see if there were any other opportunities to improve them.

.go-version

@@ -1 +1 @@
-1.18.1
+1.19.0

experiments.go

@@ -3,7 +3,8 @@ package main
 // experimentsAllowed can be set to any non-empty string using Go linker
 // arguments in order to enable the use of experimental features for a
 // particular Terraform build:
-//     go install -ldflags="-X 'main.experimentsAllowed=yes'"
+//
+//	go install -ldflags="-X 'main.experimentsAllowed=yes'"
 //
 // By default this variable is initialized as empty, in which case
 // experimental features are not available.

internal/addrs/check.go

@@ -59,9 +59,10 @@ func (c checkable) checkableSigil() {
 }
 
 // CheckType describes the category of check.
-//go:generate go run golang.org/x/tools/cmd/stringer -type=CheckType check.go
 type CheckType int
 
+//go:generate go run golang.org/x/tools/cmd/stringer -type=CheckType check.go
+
 const (
 	InvalidCondition      CheckType = 0
 	ResourcePrecondition  CheckType = 1

internal/addrs/provider.go

@@ -112,14 +112,16 @@ func NewLegacyProvider(name string) Provider {
 	}
 }
 
-// ParseProviderSourceString parses the source attribute and returns a provider.
-// This is intended primarily to parse the FQN-like strings returned by
-// terraform-config-inspect.
+// ParseProviderSourceString parses a value of the form expected in the "source"
+// argument of a required_providers entry and returns the corresponding
+// fully-qualified provider address. This is intended primarily to parse the
+// FQN-like strings returned by terraform-config-inspect.
 //
 // The following are valid source string formats:
-// 		name
-// 		namespace/name
-// 		hostname/namespace/name
+//
+//   - name
+//   - namespace/name
+//   - hostname/namespace/name
 func ParseProviderSourceString(str string) (tfaddr.Provider, tfdiags.Diagnostics) {
 	var diags tfdiags.Diagnostics
 

internal/addrs/provider_config.go

@@ -95,18 +95,18 @@ type AbsProviderConfig struct {
 var _ ProviderConfig = AbsProviderConfig{}
 
 // ParseAbsProviderConfig parses the given traversal as an absolute provider
-// address. The following are examples of traversals that can be successfully
-// parsed as absolute provider configuration addresses:
+// configuration address. The following are examples of traversals that can be
+// successfully parsed as absolute provider configuration addresses:
 //
-//     provider["registry.terraform.io/hashicorp/aws"]
-//     provider["registry.terraform.io/hashicorp/aws"].foo
-//     module.bar.provider["registry.terraform.io/hashicorp/aws"]
-//     module.bar.module.baz.provider["registry.terraform.io/hashicorp/aws"].foo
+//   - provider["registry.terraform.io/hashicorp/aws"]
+//   - provider["registry.terraform.io/hashicorp/aws"].foo
+//   - module.bar.provider["registry.terraform.io/hashicorp/aws"]
+//   - module.bar.module.baz.provider["registry.terraform.io/hashicorp/aws"].foo
 //
 // This type of address is used, for example, to record the relationships
 // between resources and provider configurations in the state structure.
-// This type of address is not generally used in the UI, except in error
-// messages that refer to provider configurations.
+// This type of address is typically not used prominently in the UI, except in
+// error messages that refer to provider configurations.
 func ParseAbsProviderConfig(traversal hcl.Traversal) (AbsProviderConfig, tfdiags.Diagnostics) {
 	modInst, remain, diags := parseModuleInstancePrefix(traversal)
 	var ret AbsProviderConfig
@@ -230,17 +230,22 @@ func ParseLegacyAbsProviderConfigStr(str string) (AbsProviderConfig, tfdiags.Dia
 }
 
 // ParseLegacyAbsProviderConfig parses the given traversal as an absolute
-// provider address. The following are examples of traversals that can be
-// successfully parsed as legacy absolute provider configuration addresses:
+// provider address in the legacy form used by Terraform v0.12 and earlier.
+// The following are examples of traversals that can be successfully parsed as
+// legacy absolute provider configuration addresses:
 //
-//     provider.aws
-//     provider.aws.foo
-//     module.bar.provider.aws
-//     module.bar.module.baz.provider.aws.foo
+//   - provider.aws
+//   - provider.aws.foo
+//   - module.bar.provider.aws
+//   - module.bar.module.baz.provider.aws.foo
 //
-// This type of address is used in legacy state and may appear in state v4 if
-// the provider config addresses have not been normalized to include provider
-// FQN.
+// We can encounter this kind of address in a historical state snapshot that
+// hasn't yet been upgraded by refreshing or applying a plan with
+// Terraform v0.13. Later versions of Terraform reject state snapshots using
+// this format, and so users must follow the Terraform v0.13 upgrade guide
+// in that case.
+//
+// We will not use this address form for any new file formats.
 func ParseLegacyAbsProviderConfig(traversal hcl.Traversal) (AbsProviderConfig, tfdiags.Diagnostics) {
 	modInst, remain, diags := parseModuleInstancePrefix(traversal)
 	var ret AbsProviderConfig
@@ -383,12 +388,12 @@ func (pc AbsProviderConfig) LegacyString() string {
 	return fmt.Sprintf("%s.%s.%s", pc.Module.String(), "provider", pc.Provider.LegacyString())
 }
 
-// String() returns a string representation of an AbsProviderConfig in the following format:
+// String() returns a string representation of an AbsProviderConfig in a format like the following examples:
 //
-// 	provider["example.com/namespace/name"]
-// 	provider["example.com/namespace/name"].alias
-// 	module.module-name.provider["example.com/namespace/name"]
-// 	module.module-name.provider["example.com/namespace/name"].alias
+//   - provider["example.com/namespace/name"]
+//   - provider["example.com/namespace/name"].alias
+//   - module.module-name.provider["example.com/namespace/name"]
+//   - module.module-name.provider["example.com/namespace/name"].alias
 func (pc AbsProviderConfig) String() string {
 	var parts []string
 	if len(pc.Module) > 0 {

internal/cloud/backend.go

@@ -920,6 +920,7 @@ func (b *Cloud) IsLocalOperations() bool {
 // as a helper to wrap any potentially colored strings.
 //
 // TODO SvH: Rename this back to Colorize as soon as we can pass -no-color.
+//
 //lint:ignore U1000 see above todo
 func (b *Cloud) cliColorize() *colorstring.Colorize {
 	if b.CLIColor != nil {

internal/command/cliconfig/provider_installation.go

@@ -294,9 +294,9 @@ type ProviderInstallationMethod struct {
 // different installation location types. The concrete implementations of
 // this interface are:
 //
-//     ProviderInstallationDirect:                install from the provider's origin registry
-//     ProviderInstallationFilesystemMirror(dir): install from a local filesystem mirror
-//     ProviderInstallationNetworkMirror(host):   install from a network mirror
+//   - [ProviderInstallationDirect]:                 install from the provider's origin registry
+//   - [ProviderInstallationFilesystemMirror] (dir): install from a local filesystem mirror
+//   - [ProviderInstallationNetworkMirror] (host):   install from a network mirror
 type ProviderInstallationLocation interface {
 	providerInstallationLocation()
 }

internal/command/command_test.go

@@ -84,16 +84,16 @@ func TestMain(m *testing.M) {
 
 // tempWorkingDir constructs a workdir.Dir object referring to a newly-created
 // temporary directory. The temporary directory is automatically removed when
-//the test and all its subtests complete.
+// the test and all its subtests complete.
 //
 // Although workdir.Dir is built to support arbitrary base directories, the
 // not-yet-migrated behaviors in command.Meta tend to expect the root module
 // directory to be the real process working directory, and so if you intend
 // to use the result inside a command.Meta object you must use a pattern
 // similar to the following when initializing your test:
 //
-//     wd := tempWorkingDir(t)
-//     defer testChdir(t, wd.RootModuleDir())()
+//	wd := tempWorkingDir(t)
+//	defer testChdir(t, wd.RootModuleDir())()
 //
 // Note that testChdir modifies global state for the test process, and so a
 // test using this pattern must never call t.Parallel().
@@ -327,9 +327,9 @@ func testStateMgrCurrentLineage(mgr statemgr.Persistent) string {
 // The given mark string is returned verbatim, to allow the following pattern
 // in tests:
 //
-//     mark := markStateForMatching(state, "foo")
-//     // (do stuff to the state)
-//     assertStateHasMarker(state, mark)
+//	mark := markStateForMatching(state, "foo")
+//	// (do stuff to the state)
+//	assertStateHasMarker(state, mark)
 func markStateForMatching(state *states.State, mark string) string {
 	state.RootModule().SetOutputValue("testing_mark", cty.StringVal(mark), false)
 	return mark
@@ -704,10 +704,10 @@ func testInputMap(t *testing.T, answers map[string]string) func() {
 // When using this function, the configuration fixture for the test must
 // include an empty configuration block for the HTTP backend, like this:
 //
-// terraform {
-//   backend "http" {
-//   }
-// }
+//	terraform {
+//	  backend "http" {
+//	  }
+//	}
 //
 // If such a block isn't present, or if it isn't empty, then an error will
 // be returned about the backend configuration having changed and that

internal/command/e2etest/doc.go

@@ -1,5 +1,5 @@
-// Package e2etest contains a small number of tests that run against a real
-// Terraform binary, compiled on the fly at the start of the test run.
+// Package e2etest contains a set of tests that run against a real Terraform
+// binary, compiled on the fly at the start of the test run.
 //
 // These tests help ensure that key end-to-end Terraform use-cases are working
 // for a real binary, whereas other tests always have at least _some_ amount
@@ -12,16 +12,16 @@
 // These tests can be used in two ways. The simplest way is to just run them
 // with "go test" as normal:
 //
-//     go test -v github.com/hashicorp/terraform/internal/command/e2etest
+//	go test -v github.com/hashicorp/terraform/internal/command/e2etest
 //
 // This will compile on the fly a Terraform binary and run the tests against
 // it.
 //
 // Alternatively, the make-archive.sh script can be used to produce a
 // self-contained zip file that can be shipped to another machine to run
 // the tests there without needing a locally-installed Go compiler. This
-// is primarily useful for testing cross-compiled builds. For more information,
-// see the commentary in make-archive.sh.
+// is primarily useful for testing cross-compiled builds during our release
+// process. For more information, see the commentary in make-archive.sh.
 //
 // The TF_ACC environment variable must be set for the tests to reach out
 // to external network services. Since these are end-to-end tests, only a

internal/command/e2etest/make-archive.sh

@@ -8,7 +8,7 @@
 # archive that can be extracted on a Windows system to run the e2e tests there:
 #    $ GOOS=windows GOARCH=amd64 ./make-archive.sh
 #
-# This will produce a zip file build/terraform-s2stest_windows_amd64.zip which
+# This will produce a zip file build/terraform-e2etest_windows_amd64.zip which
 # can be shipped off to a Windows amd64 system, extracted to some directory,
 # and then executed as follows:
 #    set TF_ACC=1

internal/command/import_test.go

@@ -809,7 +809,7 @@ func TestImportModuleVarFile(t *testing.T) {
 //
 // The specific example has a variable "foo" which is a nested object:
 //
-//   foo = { bar = { baz = true } }
+//	foo = { bar = { baz = true } }
 //
 // This is used as foo = var.foo in the call to the child module, which then
 // uses the traversal foo.bar.baz in a local. A default value in the child

internal/command/jsonplan/plan.go

@@ -708,16 +708,16 @@ func actionString(action string) []string {
 // encodePaths lossily encodes a cty.PathSet into an array of arrays of step
 // values, such as:
 //
-//   [["length"],["triggers",0,"value"]]
+//	[["length"],["triggers",0,"value"]]
 //
 // The lossiness is that we cannot distinguish between an IndexStep with string
 // key and a GetAttr step. This is fine with JSON output, because JSON's type
 // system means that those two steps are equivalent anyway: both are object
 // indexes.
 //
 // JavaScript (or similar dynamic language) consumers of these values can
-// recursively apply the steps to a given object using an index operation for
-// each step.
+// iterate over the the steps starting from the root object to reach the
+// value that each path is describing.
 func encodePaths(pathSet cty.PathSet) (json.RawMessage, error) {
 	if pathSet.Empty() {
 		return nil, nil

internal/command/workdir/normalize_path.go

@@ -21,7 +21,7 @@ import (
 // like the following, which again should be needed only in test code which
 // might need to inspect the filesystem in order to make assertions:
 //
-//     filepath.Join(d.RootModuleDir(), normalizePathResult)
+//	filepath.Join(d.RootModuleDir(), normalizePathResult)
 //
 // The above is suitable only for situations where the given path is known
 // to be beneath the working directory, which is the typical situation for

internal/configs/configload/loader.go

@@ -117,15 +117,15 @@ func (l *Loader) IsConfigDir(path string) bool {
 	return l.parser.IsConfigDir(path)
 }
 
-// ImportSources writes into the receiver's source code the given source
+// ImportSources writes into the receiver's source code map the given source
 // code buffers.
 //
 // This is useful in the situation where an ancillary loader is created for
 // some reason (e.g. loading config from a plan file) but the cached source
 // code from that loader must be imported into the "main" loader in order
 // to return source code snapshots in diagnostic messages.
 //
-//     loader.ImportSources(otherLoader.Sources())
+//	loader.ImportSources(otherLoader.Sources())
 func (l *Loader) ImportSources(sources map[string][]byte) {
 	p := l.Parser()
 	for name, src := range sources {

internal/configs/module_test.go

@@ -208,9 +208,10 @@ func TestModule_required_provider_overrides(t *testing.T) {
 // Resources without explicit provider configuration are assigned a provider
 // implied based on the resource type. For example, this resource:
 //
-//  resource foo_instance "test" { }
+//	resource "foo_instance" "test" {}
 //
-// is assigned a provider with type "foo".
+// ...is assigned to whichever provider has local name "foo" in the current
+// module.
 //
 // To find the correct provider, we first look in the module's provider
 // requirements map for a local name matching the resource type, and fall back

internal/configs/provider.go

@@ -156,8 +156,8 @@ func (p *Provider) moduleUniqueKey() string {
 // that can be successfully parsed as compact relative provider configuration
 // addresses:
 //
-//     aws
-//     aws.foo
+//   - aws
+//   - aws.foo
 //
 // This function will panic if given a relative traversal.
 //

internal/configs/variable_type_hint.go

@@ -14,9 +14,9 @@ package configs
 // are in the documentation for each constant in this enumeration, but in
 // summary:
 //
-//     TypeHintString requires a primitive type
-//     TypeHintList requires a type that could be converted to a tuple
-//     TypeHintMap requires a type that could be converted to an object
+//   - TypeHintString requires a primitive type
+//   - TypeHintList requires a type that could be converted to a tuple
+//   - TypeHintMap requires a type that could be converted to an object
 type VariableTypeHint rune
 
 //go:generate go run golang.org/x/tools/cmd/stringer -type VariableTypeHint

internal/experiments/testing.go

@@ -12,7 +12,7 @@ import (
 // that the original tables can be restored at the conclusion of the calling
 // test:
 //
-//     defer experiments.OverrideForTesting(t, current, concluded)()
+//	defer experiments.OverrideForTesting(t, current, concluded)()
 //
 // This function modifies global variables that are normally fixed throughout
 // our execution, so this function must not be called from non-test code and

internal/getproviders/package_authentication.go

@@ -382,11 +382,11 @@ type signatureAuthentication struct {
 // in turn until one is successful. If such a key is found, there are three
 // possible successful authentication results:
 //
-// 1. If the signing key is the HashiCorp official key, it is an official
-//    provider;
-// 2. Otherwise, if the signing key has a trust signature from the HashiCorp
-//    Partners key, it is a partner provider;
-// 3. If neither of the above is true, it is a community provider.
+//  1. If the signing key is the HashiCorp official key, it is an official
+//     provider;
+//  2. Otherwise, if the signing key has a trust signature from the HashiCorp
+//     Partners key, it is a partner provider;
+//  3. If neither of the above is true, it is a community provider.
 //
 // Any failure in the process of validating the signature will result in an
 // unauthenticated result.

internal/ipaddr/ip_test.go

@@ -10,9 +10,7 @@ import (
 	"testing"
 )
 
-//
 // Lean on the standard net lib as much as possible.
-//
 type IPMask = stdnet.IPMask
 
 var IPv4Mask = stdnet.IPv4Mask

internal/lang/funcs/collection.go

@@ -670,8 +670,10 @@ func Index(list, value cty.Value) (cty.Value, error) {
 	return IndexFunc.Call([]cty.Value{list, value})
 }
 
-// List takes any number of list arguments and returns a list containing those
-//  values in the same order.
+// List takes any number of arguments of types that can unify into a single
+// type and returns a list containing those values in the same order, or
+// returns an error if there is no single element type that all values can
+// convert to.
 func List(args ...cty.Value) (cty.Value, error) {
 	return ListFunc.Call(args)
 }

internal/legacy/helper/schema/resource_timeout.go

@@ -153,7 +153,6 @@ func unsupportedTimeoutKeyError(key string) error {
 //
 // StateEncode encodes the timeout into the ResourceData's InstanceState for
 // saving to state
-//
 func (t *ResourceTimeout) DiffEncode(id *terraform.InstanceDiff) error {
 	return t.metaEncode(id)
 }

internal/legacy/terraform/resource_address.go

@@ -92,7 +92,9 @@ func (r *ResourceAddress) String() string {
 
 // HasResourceSpec returns true if the address has a resource spec, as
 // defined in the documentation:
-//    https://www.terraform.io/docs/cli/state/resource-addressing.html
+//
+//	https://www.terraform.io/docs/cli/state/resource-addressing.html
+//
 // In particular, this returns false if the address contains only
 // a module path, thus addressing the entire module.
 func (r *ResourceAddress) HasResourceSpec() bool {

internal/legacy/terraform/state.go

@@ -1425,7 +1425,6 @@ func ParseResourceStateKey(k string) (*ResourceStateKey, error) {
 //
 // Extra is just extra data that a provider can return that we store
 // for later, but is not exposed in any way to the user.
-//
 type ResourceState struct {
 	// This is filled in and managed by Terraform, and is the resource
 	// type itself such as "mycloud_instance". If a resource provider sets