in codegen/src/main/kotlin/software/amazon/smithy/rust/codegen/smithy/generators/FluentClientDecorator.kt [147:271]
override fun section(section: FluentClientSection): Writable {
return when (section) {
is FluentClientSection.FluentClientDocs -> writable {
val humanName = section.serviceShape.id.name
rust(
"""
/// An ergonomic service client for `$humanName`.
///
/// This client allows ergonomic access to a `$humanName`-shaped service.
/// Each method corresponds to an endpoint defined in the service's Smithy model,
/// and the request and response shapes are auto-generated from that same model.
/// """
)
rustTemplate(
"""
/// ## Constructing a Client
///
/// To construct a client, you need a few different things:
///
/// - A [`Config`](crate::Config) that specifies additional configuration
/// required by the service.
/// - A connector (`C`) that specifies how HTTP requests are translated
/// into HTTP responses. This will typically be an HTTP client (like
/// `hyper`), though you can also substitute in your own, like a mock
/// mock connector for testing.
/// - A "middleware" (`M`) that modifies requests prior to them being
/// sent to the request. Most commonly, middleware will decide what
/// endpoint the requests should be sent to, as well as perform
/// authentication and authorization of requests (such as SigV4).
/// You can also have middleware that performs request/response
/// tracing, throttling, or other middleware-like tasks.
/// - A retry policy (`R`) that dictates the behavior for requests that
/// fail and should (potentially) be retried. The default type is
/// generally what you want, as it implements a well-vetted retry
/// policy implemented in [`RetryMode::Standard`](aws_smithy_types::retry::RetryMode::Standard).
///
/// To construct a client, you will generally want to call
/// [`Client::with_config`], which takes a [`#{client}::Client`] (a
/// Smithy client that isn't specialized to a particular service),
/// and a [`Config`](crate::Config). Both of these are constructed using
/// the [builder pattern] where you first construct a `Builder` type,
/// then configure it with the necessary parameters, and then call
/// `build` to construct the finalized output type. The
/// [`#{client}::Client`] builder is re-exported in this crate as
/// [`Builder`] for convenience.
///
/// In _most_ circumstances, you will want to use the following pattern
/// to construct a client:
///
/// ```
/// use $moduleUseName::{Builder, Client, Config};
/// let raw_client =
/// Builder::dyn_https()
/// ## /*
/// .middleware(/* discussed below */)
/// ## */
/// ## .middleware_fn(|r| r)
/// .build();
/// let config = Config::builder().build();
/// let client = Client::with_config(raw_client, config);
/// ```
///
/// For the middleware, you'll want to use whatever matches the
/// routing, authentication and authorization required by the target
/// service. For example, for the standard AWS SDK which uses
/// [SigV4-signed requests], the middleware looks like this:
///
// Ignored as otherwise we'd need to pull in all these dev-dependencies.
/// ```rust,ignore
/// use aws_endpoint::AwsEndpointStage;
/// use aws_http::user_agent::UserAgentStage;
/// use aws_sig_auth::middleware::SigV4SigningStage;
/// use aws_sig_auth::signer::SigV4Signer;
/// use aws_smithy_http_tower::map_request::MapRequestLayer;
/// use tower::layer::util::Stack;
/// use tower::ServiceBuilder;
///
/// type AwsMiddlewareStack =
/// Stack<MapRequestLayer<SigV4SigningStage>,
/// Stack<MapRequestLayer<UserAgentStage>,
/// MapRequestLayer<AwsEndpointStage>>>,
///
/// ##[derive(Debug, Default)]
/// pub struct AwsMiddleware;
/// impl<S> tower::Layer<S> for AwsMiddleware {
/// type Service = <AwsMiddlewareStack as tower::Layer<S>>::Service;
///
/// fn layer(&self, inner: S) -> Self::Service {
/// let signer = MapRequestLayer::for_mapper(SigV4SigningStage::new(SigV4Signer::new())); _signer: MapRequestLaye
/// let endpoint_resolver = MapRequestLayer::for_mapper(AwsEndpointStage); _endpoint_resolver: MapRequestLayer<Aw
/// let user_agent = MapRequestLayer::for_mapper(UserAgentStage::new()); _user_agent: MapRequestLayer<UserAgentSt
/// // These layers can be considered as occurring in order, that is:
/// // 1. Resolve an endpoint
/// // 2. Add a user agent
/// // 3. Sign
/// // (4. Dispatch over the wire)
/// ServiceBuilder::new() _ServiceBuilder<Identity>
/// .layer(endpoint_resolver) _ServiceBuilder<Stack<MapRequestLayer<_>, _>>
/// .layer(user_agent) _ServiceBuilder<Stack<MapRequestLayer<_>, _>>
/// .layer(signer) _ServiceBuilder<Stack<MapRequestLayer<_>, _>>
/// .service(inner)
/// }
/// }
/// ```
///""",
*codegenScope
)
rust(
"""
/// ## Using a Client
///
/// Once you have a client set up, you can access the service's endpoints
/// by calling the appropriate method on [`Client`]. Each such method
/// returns a request builder for that endpoint, with methods for setting
/// the various fields of the request. Once your request is complete, use
/// the `send` method to send the request. `send` returns a future, which
/// you then have to `.await` to get the service's response.
///
/// [builder pattern]: https://rust-lang.github.io/api-guidelines/type-safety.html##c-builder
/// [SigV4-signed requests]: https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html"""
)
}
else -> emptySection
}
}