Fix docs in hyper_014 module (#3282)

Moves the doc comments from HyperConnector to HyperClientBuilder where
they're more relevant, and fixes the examples.

This fix is for https://github.com/awslabs/aws-sdk-rust/issues/986.

----

_By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice._

CHANGELOG.next.toml

@@ -61,3 +61,15 @@ message = "Improve the error messages for when auth fails to select an auth sche
 references = ["smithy-rs#3277"]
 meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" }
 author = "jdisanti"
+
+[[aws-sdk-rust]]
+message = "Fix documentation and examples on HyperConnector and HyperClientBuilder."
+references = ["aws-sdk-rust#986", "smithy-rs#3282"]
+meta = { "breaking" = false, "tada" = false, "bug" = false }
+author = "jdisanti"
+
+[[smithy-rs]]
+message = "Fix documentation and examples on HyperConnector and HyperClientBuilder."
+references = ["smithy-rs#3282"]
+meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" }
+author = "jdisanti"

rust-runtime/aws-smithy-runtime/src/client/http/hyper_014.rs

@@ -132,53 +132,9 @@ pub fn default_client() -> Option<SharedHttpClient> {
 ///
 /// This connector also implements socket connect and read timeouts.
 ///
-/// # Examples
+/// This shouldn't be used directly in most cases.
-///
+/// See the docs on [`HyperClientBuilder`] for examples of how
-/// Construct a `HyperConnector` with the default TLS implementation (rustls).
+/// to customize the Hyper client.
-/// This can be useful when you want to share a Hyper connector between multiple
-/// generated Smithy clients.
-///
-/// ```no_run,ignore
-/// use aws_smithy_runtime::client::connectors::hyper_connector::{DefaultHttpsTcpConnector, HyperConnector};
-///
-/// let hyper_connector = HyperConnector::builder().build(DefaultHttpsTcpConnector::new());
-///
-/// // This connector can then be given to a generated service Config
-/// let config = my_service_client::Config::builder()
-///     .endpoint_url("http://localhost:1234")
-///     .http_connector(hyper_connector)
-///     .build();
-/// let client = my_service_client::Client::from_conf(config);
-/// ```
-///
-/// ## Use a Hyper client with WebPKI roots
-///
-/// A use case for where you may want to use the [`HyperConnector`] is when setting Hyper client settings
-/// that aren't otherwise exposed by the `Config` builder interface. Some examples include changing:
-///
-/// - Hyper client settings
-/// - Allowed TLS cipher suites
-/// - Using an alternative TLS connector library (not the default, rustls)
-/// - CA trust root certificates (illustrated using WebPKI below)
-///
-/// ```no_run,ignore
-/// use aws_smithy_runtime::client::connectors::hyper_connector::HyperConnector;
-///
-/// let https_connector = hyper_rustls::HttpsConnectorBuilder::new()
-///     .with_webpki_roots()
-///     .https_only()
-///     .enable_http1()
-///     .enable_http2()
-///     .build();
-/// let hyper_connector = HyperConnector::builder().build(https_connector);
-///
-/// // This connector can then be given to a generated service Config
-/// let config = my_service_client::Config::builder()
-///     .endpoint_url("https://example.com")
-///     .http_connector(hyper_connector)
-///     .build();
-/// let client = my_service_client::Client::from_conf(config);
-/// ```
 #[derive(Debug)]
 pub struct HyperConnector {
     adapter: Box<dyn HttpConnector>,
@@ -533,6 +489,55 @@ where
 ///
 /// This builder can be used to customize the underlying TCP connector used, as well as
 /// hyper client configuration.
+///
+/// # Examples
+///
+/// Construct a Hyper client with the default TLS implementation (rustls).
+/// This can be useful when you want to share a Hyper connector between multiple
+/// generated Smithy clients.
+///
+/// ```no_run,ignore
+/// use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder;
+///
+/// let http_client = HyperClientBuilder::new().build_https();
+///
+/// // This connector can then be given to a generated service Config
+/// let config = my_service_client::Config::builder()
+///     .endpoint_url("http://localhost:1234")
+///     .http_client(http_client)
+///     .build();
+/// let client = my_service_client::Client::from_conf(config);
+/// ```
+///
+/// ## Use a Hyper client with WebPKI roots
+///
+/// A use case for where you may want to use the [`HyperClientBuilder`] is when
+/// setting Hyper client settings that aren't otherwise exposed by the `Config`
+/// builder interface. Some examples include changing:
+///
+/// - Hyper client settings
+/// - Allowed TLS cipher suites
+/// - Using an alternative TLS connector library (not the default, rustls)
+/// - CA trust root certificates (illustrated using WebPKI below)
+///
+/// ```no_run,ignore
+/// use aws_smithy_runtime::client::http::hyper_014::HyperClientBuilder;
+///
+/// let https_connector = hyper_rustls::HttpsConnectorBuilder::new()
+///     .with_webpki_roots()
+///     .https_only()
+///     .enable_http1()
+///     .enable_http2()
+///     .build();
+/// let http_client = HyperClientBuilder::new().build(https_connector);
+///
+/// // This connector can then be given to a generated service Config
+/// let config = my_service_client::Config::builder()
+///     .endpoint_url("https://example.com")
+///     .http_client(http_client)
+///     .build();
+/// let client = my_service_client::Client::from_conf(config);
+/// ```
 #[derive(Clone, Default, Debug)]
 pub struct HyperClientBuilder {
     client_builder: Option<hyper_0_14::client::Builder>,