From e3c589fcd2a958024cb698450c153a9ba866cebf Mon Sep 17 00:00:00 2001
From: Luc Talatinian <102624213+lucix-aws@users.noreply.github.com>
Date: Mon, 3 Jun 2024 13:34:45 -0400
Subject: [PATCH] add missing deprecation docs on global EndpointResolver
 interfaces (#2665)

---
 .../c97f23ee44fe4305b699c524e2f9fe19.json     |  9 +++++++
 aws/endpoints.go                              | 26 ++++++++++++++++---
 config/load_options.go                        | 12 ++++++++-
 3 files changed, 42 insertions(+), 5 deletions(-)
 create mode 100644 .changelog/c97f23ee44fe4305b699c524e2f9fe19.json

diff --git a/.changelog/c97f23ee44fe4305b699c524e2f9fe19.json b/.changelog/c97f23ee44fe4305b699c524e2f9fe19.json
new file mode 100644
index 00000000000..810d7012afc
--- /dev/null
+++ b/.changelog/c97f23ee44fe4305b699c524e2f9fe19.json
@@ -0,0 +1,9 @@
+{
+    "id": "c97f23ee-44fe-4305-b699-c524e2f9fe19",
+    "type": "documentation",
+    "description": "Add deprecation docs to global endpoint resolution interfaces. These APIs were previously deprecated with the introduction of service-specific endpoint resolution (EndpointResolverV2 and BaseEndpoint on service client options).",
+    "modules": [
+        ".",
+        "config"
+    ]
+}
diff --git a/aws/endpoints.go b/aws/endpoints.go
index aa10a9b40f0..99edbf3ee63 100644
--- a/aws/endpoints.go
+++ b/aws/endpoints.go
@@ -70,6 +70,10 @@ func GetUseFIPSEndpoint(options ...interface{}) (value FIPSEndpointState, found
 // The SDK will automatically resolve these endpoints per API client using an
 // internal endpoint resolvers. If you'd like to provide custom endpoint
 // resolving behavior you can implement the EndpointResolver interface.
+//
+// Deprecated: This structure was used with the global [EndpointResolver]
+// interface, which has been deprecated in favor of service-specific endpoint
+// resolution. See the deprecation docs on that interface for more information.
 type Endpoint struct {
 	// The base URL endpoint the SDK API clients will use to make API calls to.
 	// The SDK will suffix URI path and query elements to this endpoint.
@@ -124,6 +128,8 @@ type Endpoint struct {
 }
 
 // EndpointSource is the endpoint source type.
+//
+// Deprecated: The global [Endpoint] structure is deprecated.
 type EndpointSource int
 
 const (
@@ -161,19 +167,25 @@ func (e *EndpointNotFoundError) Unwrap() error {
 // API clients will fallback to attempting to resolve the endpoint using its
 // internal default endpoint resolver.
 //
-// Deprecated: See EndpointResolverWithOptions
+// Deprecated: The global endpoint resolution interface is deprecated. The API
+// for endpoint resolution is now unique to each service and is set via the
+// EndpointResolverV2 field on service client options. Setting a value for
+// EndpointResolver on aws.Config or service client options will prevent you
+// from using any endpoint-related service features released after the
+// introduction of EndpointResolverV2. You may also encounter broken or
+// unexpected behavior when using the old global interface with services that
+// use many endpoint-related customizations such as S3.
 type EndpointResolver interface {
 	ResolveEndpoint(service, region string) (Endpoint, error)
 }
 
 // EndpointResolverFunc wraps a function to satisfy the EndpointResolver interface.
 //
-// Deprecated: See EndpointResolverWithOptionsFunc
+// Deprecated: The global endpoint resolution interface is deprecated. See
+// deprecation docs on [EndpointResolver].
 type EndpointResolverFunc func(service, region string) (Endpoint, error)
 
 // ResolveEndpoint calls the wrapped function and returns the results.
-//
-// Deprecated: See EndpointResolverWithOptions.ResolveEndpoint
 func (e EndpointResolverFunc) ResolveEndpoint(service, region string) (Endpoint, error) {
 	return e(service, region)
 }
@@ -184,11 +196,17 @@ func (e EndpointResolverFunc) ResolveEndpoint(service, region string) (Endpoint,
 // available. If the EndpointResolverWithOptions returns an EndpointNotFoundError error,
 // API clients will fallback to attempting to resolve the endpoint using its
 // internal default endpoint resolver.
+//
+// Deprecated: The global endpoint resolution interface is deprecated. See
+// deprecation docs on [EndpointResolver].
 type EndpointResolverWithOptions interface {
 	ResolveEndpoint(service, region string, options ...interface{}) (Endpoint, error)
 }
 
 // EndpointResolverWithOptionsFunc wraps a function to satisfy the EndpointResolverWithOptions interface.
+//
+// Deprecated: The global endpoint resolution interface is deprecated. See
+// deprecation docs on [EndpointResolver].
 type EndpointResolverWithOptionsFunc func(service, region string, options ...interface{}) (Endpoint, error)
 
 // ResolveEndpoint calls the wrapped function and returns the results.
diff --git a/config/load_options.go b/config/load_options.go
index 06596c1b7c8..7ff38b9da84 100644
--- a/config/load_options.go
+++ b/config/load_options.go
@@ -824,7 +824,14 @@ func (o LoadOptions) getEndpointResolver(ctx context.Context) (aws.EndpointResol
 // the EndpointResolver value is ignored. If multiple WithEndpointResolver calls
 // are made, the last call overrides the previous call values.
 //
-// Deprecated: See WithEndpointResolverWithOptions
+// Deprecated: The global endpoint resolution interface is deprecated. The API
+// for endpoint resolution is now unique to each service and is set via the
+// EndpointResolverV2 field on service client options. Use of
+// WithEndpointResolver or WithEndpointResolverWithOptions will prevent you
+// from using any endpoint-related service features released after the
+// introduction of EndpointResolverV2. You may also encounter broken or
+// unexpected behavior when using the old global interface with services that
+// use many endpoint-related customizations such as S3.
 func WithEndpointResolver(v aws.EndpointResolver) LoadOptionsFunc {
 	return func(o *LoadOptions) error {
 		o.EndpointResolver = v
@@ -844,6 +851,9 @@ func (o LoadOptions) getEndpointResolverWithOptions(ctx context.Context) (aws.En
 // that sets the EndpointResolverWithOptions on LoadOptions. If the EndpointResolverWithOptions is set to nil,
 // the EndpointResolver value is ignored. If multiple WithEndpointResolver calls
 // are made, the last call overrides the previous call values.
+//
+// Deprecated: The global endpoint resolution interface is deprecated. See
+// deprecation docs on [WithEndpointResolver].
 func WithEndpointResolverWithOptions(v aws.EndpointResolverWithOptions) LoadOptionsFunc {
 	return func(o *LoadOptions) error {
 		o.EndpointResolverWithOptions = v