Lots of doc tweaks and cleanups (smithy-lang#693)

Author: rcoh

aws/rust-runtime/aws-config/src/default_provider.rs

@@ -3,7 +3,11 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 
-//! Default Provider chains for [`region`](default_provider::region) and credentials (TODO)
+//! Default Provider chains for [`region`](default_provider::region) and [`credentials`](default_provider::credentials).
+//!
+//! Unless specific configuration is required, these should be constructed via [`ConfigLoader`](crate::ConfigLoader).
+//!
+//!
 
 /// Default region provider chain
 pub mod region {

aws/rust-runtime/aws-config/src/lib.rs

@@ -1,13 +1,15 @@
 #![deny(missing_docs)]
 
-//! `aws-config` provides implementations of region, credential (todo), and connector (todo) resolution.
+//! `aws-config` provides implementations of region, credential resolution.
+//!
+//! These implementations can be used either via the default chain implementation
+//! [`from_env`]/[`ConfigLoader`] or ad-hoc individual credential and region providers.
 //!
-//! These implementations can be used either adhoc or via [`from_env`](from_env)/[`ConfigLoader`](ConfigLoader).
 //! [`ConfigLoader`](ConfigLoader) can combine different configuration sources into an AWS shared-config:
 //! [`Config`](aws_types::config::Config). [`Config`](aws_types::config::Config) can be used configure
 //! an AWS service client.
 //!
-//! ## Examples
+//! # Examples
 //! Load default SDK configuration:
 //! ```rust
 //! # mod aws_sdk_dynamodb {
@@ -66,7 +68,7 @@ pub mod provider_config;
 
 /// Create an environment loader for AWS Configuration
 ///
-/// ## Example
+/// # Examples
 /// ```rust
 /// # async fn create_config() {
 /// use aws_types::region::Region;
@@ -112,7 +114,7 @@ mod loader {
     impl ConfigLoader {
         /// Override the region used to build [`Config`](aws_types::config::Config).
         ///
-        /// # Example
+        /// # Examples
         /// ```rust
         /// # async fn create_config() {
         /// use aws_types::region::Region;
@@ -127,7 +129,7 @@ mod loader {
         }
 
         /// Override the credentials provider used to build [`Config`](aws_types::config::Config).
-        /// # Example
+        /// # Examples
         /// Override the credentials provider but load the default value for region:
         /// ```rust
         /// # use aws_types::Credentials;

aws/rust-runtime/aws-config/src/meta/credentials/chain.rs

@@ -18,7 +18,7 @@ use tracing::Instrument;
 ///   the next provider will be checked.
 /// * Finally, if a provider returns any other error condition, an error will be returned immediately.
 ///
-/// ## Example
+/// # Examples
 /// ```rust
 /// use aws_config::meta::credentials::CredentialsProviderChain;
 /// use aws_types::Credentials;

aws/rust-runtime/aws-config/src/meta/credentials/credential_fn.rs

@@ -36,7 +36,7 @@ where
 /// to create an [`ProvideCredentials`] implementation from an async block that returns
 /// a [`credentials::Result`].
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use aws_types::Credentials;

aws/rust-runtime/aws-config/src/meta/credentials/lazy_caching.rs

@@ -125,7 +125,7 @@ mod builder {
 
     /// Builder for constructing a [`LazyCachingCredentialsProvider`].
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```
     /// use aws_types::Credentials;

aws/rust-runtime/aws-config/src/meta/credentials/mod.rs

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 
+//! Credential providers that augment an existing credentials providers to add functionality
+
 mod chain;
 pub use chain::CredentialsProviderChain;
 

aws/rust-runtime/aws-config/src/meta/mod.rs

@@ -3,8 +3,6 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 
-/// Region Providers
 pub mod region;
 
-/// Credential Providers
 pub mod credentials;

aws/rust-runtime/aws-config/src/meta/region.rs

@@ -3,14 +3,16 @@
  * SPDX-License-Identifier: Apache-2.0.
  */
 
+//! Region providers that augment existing providers with new functionality
+
 use aws_types::region::Region;
 use std::borrow::Cow;
 use std::fmt::Debug;
 use tracing::Instrument;
 
 /// Load a region by selecting the first from a series of region providers.
 ///
-/// # Example
+/// # Examples
 /// ```rust
 /// use aws_types::region::Region;
 /// use std::env;

aws/rust-runtime/aws-config/src/profile/credentials.rs

@@ -293,7 +293,7 @@ pub struct Builder {
 impl Builder {
     /// Override the configuration for the [`ProfileFileCredentialsProvider`]
     ///
-    /// # Example
+    /// # Examples
     /// ```rust
     /// # async fn test() {
     /// use aws_config::profile::ProfileFileCredentialsProvider;
@@ -310,7 +310,7 @@ impl Builder {
 
     /// Adds a custom credential source
     ///
-    /// # Example
+    /// # Examples
     ///
     /// ```rust
     /// use aws_types::credentials::{self, ProvideCredentials, future};

aws/rust-runtime/aws-config/src/profile/credentials/exec.rs

@@ -18,7 +18,7 @@ use crate::web_identity_token::{StaticConfiguration, WebIdentityTokenCredentials
 use aws_types::credentials::{self, CredentialsError, ProvideCredentials};
 use aws_types::os_shim_internal::Fs;
 use smithy_client::erase::DynConnector;
-use std::fmt::{Debug, Formatter};
+use std::fmt::Debug;
 
 #[derive(Debug)]
 pub struct AssumeRoleProvider {
@@ -66,18 +66,12 @@ impl AssumeRoleProvider {
     }
 }
 
+#[derive(Debug)]
 pub(super) struct ProviderChain {
     base: Arc<dyn ProvideCredentials>,
     chain: Vec<AssumeRoleProvider>,
 }
 
-impl Debug for ProviderChain {
-    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
-        // TODO: ProvideCredentials should probably mandate debug
-        f.debug_struct("ProviderChain").finish()
-    }
-}
-
 impl ProviderChain {
     pub fn base(&self) -> &dyn ProvideCredentials {
         self.base.as_ref()