Merge pull request #1800 from gruntwork-io/james/oss-3391-3394-godoc-deprecation

docs: add godoc and Deprecated annotations for v1 surface

Author: james00012

modules/aws/account.go

@@ -59,13 +59,17 @@ func GetAccountIDE(t testing.TestingT) (string, error) {
 	return GetAccountIDContextE(t, context.Background())
 }
 
+// GetAccountId gets the Account ID for the currently logged in IAM User.
+//
 // Deprecated: Use [GetAccountID] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
 func GetAccountId(t testing.TestingT) string {
 	return GetAccountID(t)
 }
 
+// GetAccountIdE gets the Account ID for the currently logged in IAM User.
+//
 // Deprecated: Use [GetAccountIDE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/ami.go

@@ -209,13 +209,19 @@ func GetMostRecentAmiIDE(t testing.TestingT, region string, ownerID string, filt
 	return GetMostRecentAmiIDContextE(t, context.Background(), region, ownerID, filters)
 }
 
+// GetMostRecentAmiId gets the ID of the most recent AMI in the given region that has the given owner and matches
+// the given filters.
+//
 // Deprecated: Use [GetMostRecentAmiID] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
 func GetMostRecentAmiId(t testing.TestingT, region string, ownerId string, filters map[string][]string) string {
 	return GetMostRecentAmiID(t, region, ownerId, filters)
 }
 
+// GetMostRecentAmiIdE gets the ID of the most recent AMI in the given region that has the given owner and matches
+// the given filters.
+//
 // Deprecated: Use [GetMostRecentAmiIDE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/auth.go

@@ -17,7 +17,9 @@ import (
 )
 
 const (
-	AuthAssumeRoleEnvVar = "TERRATEST_IAM_ROLE" // OS environment variable name through which Assume Role ARN may be passed for authentication
+	// AuthAssumeRoleEnvVar is the OS environment variable name through which an
+	// Assume Role ARN may be passed for authentication.
+	AuthAssumeRoleEnvVar = "TERRATEST_IAM_ROLE"
 )
 
 // NewAuthenticatedSessionContext creates an AWS Config following to standard AWS authentication workflow.

modules/aws/dynamodb.go

@@ -74,6 +74,8 @@ func GetDynamoDBTableTagsE(t testing.TestingT, region string, tableName string)
 	return GetDynamoDBTableTagsContextE(t, context.Background(), region, tableName)
 }
 
+// GetDynamoDbTableTags fetches resource tags of a specified dynamoDB table. This will fail the test if there are any errors.
+//
 // Deprecated: Use [GetDynamoDBTableTagsContext] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name
@@ -82,6 +84,8 @@ func GetDynamoDbTableTags(t testing.TestingT, region string, tableName string) [
 	return GetDynamoDBTableTagsContext(t, context.Background(), region, tableName)
 }
 
+// GetDynamoDbTableTagsE fetches resource tags of a specified dynamoDB table.
+//
 // Deprecated: Use [GetDynamoDBTableTagsContextE] instead.
 //
 //nolint:staticcheck,revive // preserving deprecated function name

modules/aws/ec2-files.go

@@ -394,6 +394,10 @@ func FetchFilesFromAsgsPE(t testing.TestingT, awsRegion string, spec *RemoteFile
 	return FetchFilesFromAsgsPContextE(t, context.Background(), awsRegion, spec)
 }
 
+// FetchFilesFromAsgs looks up the EC2 Instances in all the ASGs given in the
+// RemoteFileSpecification, downloads the matching files from each instance,
+// and stores them locally as described in [FetchFilesFromAsgsPContext].
+//
 // Deprecated: Use [FetchFilesFromAsgsPContext] instead.
 //
 //nolint:staticcheck,revive,gocritic // preserving deprecated function name
@@ -403,6 +407,8 @@ func FetchFilesFromAsgs(t testing.TestingT, awsRegion string, spec RemoteFileSpe
 	FetchFilesFromAsgsPContext(t, context.Background(), awsRegion, &spec)
 }
 
+// FetchFilesFromAsgsE is the error-returning equivalent of [FetchFilesFromAsgs].
+//
 // Deprecated: Use [FetchFilesFromAsgsPContextE] instead.
 //
 //nolint:staticcheck,revive,gocritic // preserving deprecated function name

modules/aws/errors.go

@@ -5,6 +5,8 @@ import (
 )
 
 // IpForEc2InstanceNotFound is an error that occurs when the IP for an EC2 instance is not found.
+//
+// Deprecated: Use [IPForEc2InstanceNotFound] instead.
 type IpForEc2InstanceNotFound struct { //nolint:staticcheck,revive // preserving deprecated type name
 	InstanceId string //nolint:staticcheck,revive // preserving existing field name
 	AwsRegion  string
@@ -40,6 +42,7 @@ func (err NotFoundError) Error() string {
 	return fmt.Sprintf("Object of type %s with id %s not found in region %s", err.objectType, err.objectID, err.region)
 }
 
+// NewNotFoundError returns a [NotFoundError] for the given object type, ID, and region.
 func NewNotFoundError(objectType string, objectID string, region string) NotFoundError {
 	return NotFoundError{objectType, objectID, region}
 }
@@ -60,6 +63,8 @@ func (err AsgCapacityNotMetError) Error() string {
 	)
 }
 
+// NewAsgCapacityNotMetError returns an [AsgCapacityNotMetError] describing
+// the given ASG's desired and current capacities.
 func NewAsgCapacityNotMetError(asgName string, desiredCapacity int64, currentCapacity int64) AsgCapacityNotMetError {
 	return AsgCapacityNotMetError{asgName, desiredCapacity, currentCapacity}
 }
@@ -80,6 +85,8 @@ func (err BucketVersioningNotEnabledError) Error() string {
 	)
 }
 
+// NewBucketVersioningNotEnabledError returns a [BucketVersioningNotEnabledError]
+// for the given S3 bucket, region, and observed versioning status.
 func NewBucketVersioningNotEnabledError(s3BucketName string, awsRegion string, versioningStatus string) BucketVersioningNotEnabledError {
 	return BucketVersioningNotEnabledError{s3BucketName: s3BucketName, awsRegion: awsRegion, versioningStatus: versioningStatus}
 }
@@ -99,6 +106,8 @@ func (err NoBucketPolicyError) Error() string {
 	)
 }
 
+// NewNoBucketPolicyError returns a [NoBucketPolicyError] for the given S3
+// bucket, region, and bucket policy.
 func NewNoBucketPolicyError(s3BucketName string, awsRegion string, bucketPolicy string) NoBucketPolicyError {
 	return NoBucketPolicyError{s3BucketName: s3BucketName, awsRegion: awsRegion, bucketPolicy: bucketPolicy}
 }

modules/aws/lambda.go

@@ -12,13 +12,24 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+// InvocationTypeOption identifies the invocation mode passed to AWS Lambda
+// when calling [InvokeFunctionWithParamsContextE]. See the
+// InvocationType-prefixed constants for the supported values.
 type InvocationTypeOption string
 
+// Supported [InvocationTypeOption] values for Lambda invocation modes.
 const (
+	// InvocationTypeRequestResponse invokes the function synchronously, keeping
+	// the connection open until the function returns a response or times out.
 	InvocationTypeRequestResponse InvocationTypeOption = "RequestResponse"
-	InvocationTypeDryRun          InvocationTypeOption = "DryRun"
+	// InvocationTypeDryRun validates parameter values and verifies that the user
+	// or role has permission to invoke the function, without actually invoking it.
+	InvocationTypeDryRun InvocationTypeOption = "DryRun"
 )
 
+// Value returns the string form of the [InvocationTypeOption], defaulting to
+// [InvocationTypeRequestResponse] when itype is nil. It returns an error if
+// itype is set to a value that is not one of the supported invocation types.
 func (itype *InvocationTypeOption) Value() (string, error) {
 	if itype != nil {
 		switch *itype {
@@ -212,6 +223,9 @@ func InvokeFunctionWithParamsE(t testing.TestingT, region, functionName string,
 	return InvokeFunctionWithParamsContextE(t, context.Background(), region, functionName, input)
 }
 
+// FunctionError is returned when an AWS Lambda invocation reports a function
+// error in its response. It carries the error message, the HTTP status code,
+// and the raw payload returned by the function.
 type FunctionError struct {
 	Message    string
 	Payload    []byte

modules/aws/rds.go

@@ -698,6 +698,8 @@ func GetValidEngineVersionE(t testing.TestingT, region string, engine string, ma
 
 // ParameterForDbInstanceNotFound is an error that occurs when the parameter group specified is not found for the DB instance.
 //
+// Deprecated: Use [ParameterForDBInstanceNotFound] instead.
+//
 //nolint:staticcheck,revive // preserving existing type name
 type ParameterForDbInstanceNotFound struct {
 	ParameterName string
@@ -714,6 +716,8 @@ func (err ParameterForDbInstanceNotFound) Error() string {
 
 // OptionGroupOptionSettingForDbInstanceNotFound is an error that occurs when the option setting specified is not found in the option group of the DB instance.
 //
+// Deprecated: Use [OptionGroupOptionSettingForDBInstanceNotFound] instead.
+//
 //nolint:staticcheck,revive // preserving existing type name
 type OptionGroupOptionSettingForDbInstanceNotFound struct {
 	OptionName        string

modules/logger/logger.go

@@ -114,7 +114,6 @@ func (terratestLogger) Logf(t testing.TestingT, format string, args ...any) {
 	DoLog(t, callDepthWrapped, os.Stdout, fmt.Sprintf(format, args...))
 }
 
-// Deprecated: use Logger instead, as it provides more flexibility on logging.
 // Logf logs the given format and arguments, formatted using fmt.Sprintf, to stdout, along with a timestamp and information
 // about what test and file is doing the logging. Before Go 1.14, this is an alternative to t.Logf as it logs to stdout
 // immediately, rather than buffering all log output and only displaying it at the very end of the test. This is useful
@@ -132,6 +131,8 @@ func (terratestLogger) Logf(t testing.TestingT, format string, args ...any) {
 //     this log method, you get log output continuously.
 //
 // Although t.Logf now supports streaming output since Go 1.14, this is kept for compatibility purposes.
+//
+// Deprecated: use Logger instead, as it provides more flexibility on logging.
 func Logf(t testing.TestingT, format string, args ...any) {
 	if tt, ok := t.(helper); ok {
 		tt.Helper()

modules/opa/eval.go

@@ -49,9 +49,13 @@ type EvalOptions struct {
 // defined value (FailDefined), or not at all (NoFail).
 type FailMode int
 
+// FailMode values for [EvalOptions.FailMode] that control when `opa eval` should fail.
 const (
+	// FailUndefined causes `opa eval` to fail when the query returns an undefined value.
 	FailUndefined FailMode = iota
+	// FailDefined causes `opa eval` to fail when the query returns a defined value.
 	FailDefined
+	// NoFail causes `opa eval` not to fail based on the query result.
 	NoFail
 )