misc: add clarifying docs for endpointProvider (#822)

Author: lucix-aws

.changes/ce8cc156-ee47-40ce-8ef7-7c3fca2e9536.json

@@ -0,0 +1,5 @@
+{
+    "id": "ce8cc156-ee47-40ce-8ef7-7c3fca2e9536",
+    "type": "misc",
+    "description": "Add clarifying documentation for `endpointProvider` in client config."
+}

codegen/smithy-kotlin-codegen/src/main/kotlin/software/amazon/smithy/kotlin/codegen/rendering/ServiceClientConfigGenerator.kt

@@ -12,6 +12,7 @@ import software.amazon.smithy.kotlin.codegen.model.expectTrait
 import software.amazon.smithy.kotlin.codegen.model.hasIdempotentTokenMember
 import software.amazon.smithy.kotlin.codegen.model.hasTrait
 import software.amazon.smithy.kotlin.codegen.rendering.endpoints.DefaultEndpointProviderGenerator
+import software.amazon.smithy.kotlin.codegen.rendering.endpoints.EndpointParametersGenerator
 import software.amazon.smithy.kotlin.codegen.rendering.endpoints.EndpointProviderGenerator
 import software.amazon.smithy.kotlin.codegen.rendering.util.AbstractConfigGenerator
 import software.amazon.smithy.kotlin.codegen.rendering.util.ConfigProperty
@@ -63,14 +64,24 @@ class ServiceClientConfigGenerator(
                 val hasRules = shape.hasTrait<EndpointRuleSetTrait>()
                 symbol = EndpointProviderGenerator.getSymbol(context.settings)
                 propertyType = if (hasRules) { // if there's a ruleset, we have a usable default, otherwise caller has to provide their own
-                    additionalImports = listOf(DefaultEndpointProviderGenerator.getSymbol(context.settings))
                     ConfigPropertyType.RequiredWithDefault("DefaultEndpointProvider()")
                 } else {
                     ConfigPropertyType.Required()
                 }
                 documentation = """
-                    The endpoint provider used to determine where to make service requests.
+                    The endpoint provider used to determine where to make service requests. **This is an advanced config
+                    option.**
+
+                    Endpoint resolution occurs as part of the workflow for every request made via the service client.
+
+                    The inputs to endpoint resolution are defined on a per-service basis (see [EndpointParameters]).
                 """.trimIndent()
+                additionalImports = buildList {
+                    add(EndpointParametersGenerator.getSymbol(context.settings))
+                    if (hasRules) {
+                        add(DefaultEndpointProviderGenerator.getSymbol(context.settings))
+                    }
+                }
             },
         )
     }

codegen/smithy-kotlin-codegen/src/test/kotlin/software/amazon/smithy/kotlin/codegen/rendering/ServiceClientConfigGeneratorTest.kt

@@ -74,7 +74,12 @@ public class Config private constructor(builder: Builder) : HttpClientConfig, Id
         override var httpClientEngine: HttpClientEngine? = null
 
         /**
-         * The endpoint provider used to determine where to make service requests.
+         * The endpoint provider used to determine where to make service requests. **This is an advanced config
+         * option.**
+         *
+         * Endpoint resolution occurs as part of the workflow for every request made via the service client.
+         *
+         * The inputs to endpoint resolution are defined on a per-service basis (see [EndpointParameters]).
          */
         public var endpointProvider: EndpointProvider? = null
 
@@ -252,7 +257,12 @@ public class Config private constructor(builder: Builder) {
         public var customProp: Int? = null
 
         /**
-         * The endpoint provider used to determine where to make service requests.
+         * The endpoint provider used to determine where to make service requests. **This is an advanced config
+         * option.**
+         *
+         * Endpoint resolution occurs as part of the workflow for every request made via the service client.
+         *
+         * The inputs to endpoint resolution are defined on a per-service basis (see [EndpointParameters]).
          */
         public var endpointProvider: EndpointProvider? = null
 

tests/codegen/paginator-tests/src/main/kotlin/com/test/endpoints/EndpointParameters.kt

@@ -0,0 +1,3 @@
+package com.test.endpoints
+
+class EndpointParameters

tests/codegen/paginator-tests/src/main/kotlin/com/test/endpoints/EndpointProvider.kt

@@ -3,4 +3,4 @@ package com.test.endpoints
 /**
  * Stubbed EndpointProvider since we don't use a concrete protocol generator for this test.
  */
-typealias EndpointProvider = aws.smithy.kotlin.runtime.client.endpoints.EndpointProvider<Unit>
+typealias EndpointProvider = aws.smithy.kotlin.runtime.client.endpoints.EndpointProvider<EndpointParameters>

tests/codegen/waiter-tests/src/main/kotlin/com/test/endpoints/EndpointParameters.kt

@@ -0,0 +1,3 @@
+package com.test.endpoints
+
+class EndpointParameters

tests/codegen/waiter-tests/src/main/kotlin/com/test/endpoints/EndpointProvider.kt

@@ -3,4 +3,4 @@ package com.test.endpoints
 /**
  * Stubbed EndpointProvider since we don't use a concrete protocol generator for this test.
  */
-typealias EndpointProvider = aws.smithy.kotlin.runtime.client.endpoints.EndpointProvider<Unit>
+typealias EndpointProvider = aws.smithy.kotlin.runtime.client.endpoints.EndpointProvider<EndpointParameters>