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()

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

@@ -6,13 +6,16 @@
 //! Load configuration from AWS Profiles
 //!
 //! AWS profiles are typically stored in `~/.aws/config` and `~/.aws/credentials`. For more details
-//! see <todo>
+//! see the [`load`](parser::load) function.
 
 mod parser;
+#[doc(inline)]
 pub use parser::{load, Profile, ProfileSet, Property};
 
 pub mod credentials;
 pub mod region;
 
+#[doc(inline)]
 pub use credentials::ProfileFileCredentialsProvider;
+#[doc(inline)]
 pub use region::ProfileFileRegionProvider;

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

@@ -17,13 +17,16 @@ pub use self::parse::ProfileParseError;
 
 /// Read & parse AWS config files
 ///
-/// Loads and parses profile files according to the spec:
+/// Loads AWS config file from the filesystem, parses them, and converts them into a [`ProfileSet`](ProfileSet).
+///
+/// Although the basic behavior is straightforward, there are number of nuances to maintain backwards
+/// compatibility with other SDKs enumerated below.
 ///
 /// ## Location of Profile Files
-/// * The location of the config file will be loaded from `$AWS_CONFIG_FILE` with a fallback to
-///   `~/.aws/config`
-/// * The location of the credentials file will be loaded from `$AWS_SHARED_CREDENTIALS_FILE` with a
-///   fallback to `~/.aws/credentials`
+/// * The location of the config file will be loaded from the `AWS_CONFIG_FILE` environment variable
+/// with a fallback to `~/.aws/config`
+/// * The location of the credentials file will be loaded from the `AWS_SHARED_CREDENTIALS_FILE`
+/// environment variable with a fallback to `~/.aws/credentials`
 ///
 /// ## Home directory resolution
 /// Home directory resolution is implemented to match the behavior of the CLI & Python. `~` is only
@@ -33,15 +36,15 @@ pub use self::parse::ProfileParseError;
 ///   resolve to the home directory.
 ///
 /// When determining the home directory, the following environment variables are checked:
-/// - `$HOME` on all platforms
-/// - `$USERPROFILE` on Windows
-/// - `$HOMEDRIVE$HOMEPATH` on Windows
+/// - `HOME` on all platforms
+/// - `USERPROFILE` on Windows
+/// - The concatenation of `HOMEDRIVE` and `HOMEPATH` on Windows (`$HOMEDRIVE$HOMEPATH`)
 ///
 /// ## Profile file syntax
 ///
-/// Profile files have a general form similar to INI but with a number of quirks and edge cases. These
-/// behaviors are largely to match existing parser implementations and these cases are documented in `test-data/profile-parser-tests.json`
-/// in this repo.
+/// Profile files have a form similar to `.ini` but with a several edge cases. These behaviors exist
+/// to match existing parser implementations, ensuring consistent behavior across AWS SDKs. These
+/// cases fully enumerated in `test-data/profile-parser-tests.json`.
 ///
 /// ### The config file `~/.aws/config`
 /// ```ini
@@ -76,11 +79,12 @@ pub struct ProfileSet {
 }
 
 impl ProfileSet {
+    #[doc(hidden)]
     /// Create a new Profile set directly from a HashMap
     ///
     /// This method creates a ProfileSet directly from a hashmap with no normalization.
     ///
-    /// ## Note
+    /// ## Warning
     ///
     /// This is probably not what you want! In general, [`load`](load) should be used instead
     /// because it will perform input normalization. However, for tests which operate on the
@@ -113,7 +117,7 @@ impl ProfileSet {
             .and_then(|profile| profile.get(key))
     }
 
-    /// Retrieve a named profile from the profile set
+    /// Retrieves a named profile from the profile set
     pub fn get_profile(&self, profile_name: &str) -> Option<&Profile> {
         self.profiles.get(profile_name)
     }
@@ -214,9 +218,9 @@ mod test {
     use std::fs;
     use tracing_test::traced_test;
 
-    /// Run all tests from profile-parser-tests.json
+    /// Run all tests from `test-data/profile-parser-tests.json`
     ///
-    /// These represent the bulk of the test cases and reach effectively 100% coverage
+    /// These represent the bulk of the test cases and reach 100% coverage of the parser.
     #[test]
     #[traced_test]
     fn run_tests() -> Result<(), Box<dyn Error>> {

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

@@ -15,15 +15,23 @@ use aws_types::region::Region;
 /// This provider will attempt to load AWS shared configuration, then read the `region` property
 /// from the active profile.
 ///
-/// Example:
+/// # Examples
 ///
+/// **Loads "us-west-2" as the region
 /// ```ini
-/// # `~/.aws/config
 /// [default]
 /// region = us-west-2
 /// ```
 ///
-/// This provider is part of the [default provider chain](crate::default_provider::region).
+/// **Loads `us-east-1` as the region _if and only if_ the `AWS_PROFILE` environment variable is set
+/// to `other`.
+///
+/// ```ini
+/// [profile other]
+/// region = us-east-1
+/// ```
+///
+/// This provider is part of the [default region provider chain](crate::default_provider::region).
 #[derive(Debug, Default)]
 pub struct ProfileFileRegionProvider {
     fs: Fs,

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

@@ -52,7 +52,7 @@ impl ProviderConfig {
     /// a `ProviderConfig` without these fields set, use [`ProviderConfig::empty`].
     ///
     ///
-    /// # Example
+    /// # Examples
     /// ```rust
     /// use aws_config::provider_config::ProviderConfig;
     /// use aws_sdk_sts::Region;
@@ -80,7 +80,7 @@ impl ProviderConfig {
 
     /// Create a default provider config with the region region automatically loaded from the default chain.
     ///
-    /// # Example
+    /// # Examples
     /// ```rust
     /// # async fn test() {
     /// use aws_config::provider_config::ProviderConfig;

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

@@ -5,15 +5,26 @@
 
 //! Load Credentials from Web Identity Tokens
 //!
-//! WebIdentity tokens can be loaded via environment variables, or via profiles:
+//! Web identity tokens can be loaded from file. The path may be set in one of three ways:
+//! 1. [Environment Variables](#environment-variable-configuration)
+//! 2. [AWS profile](#aws-profile-configuration) defined in `~/.aws/config`
+//! 3. Static configuration via [`static_configuration`](Builder::static_configuration)
 //!
-//! ## Via Environment Variables
+//! **Note:** [WebIdentityTokenCredentialsProvider] is part of the [default provider chain](crate::default_provider).
+//! Unless you need specific behavior or configuration overrides, it is recommended to use the
+//! default chain instead of using this provider directly. This client should be considered a "low level"
+//! client as it does not include caching or profile-file resolution when used in isolation.
+//!
+//! ## Environment Variable Configuration
 //! WebIdentityTokenCredentialProvider will load the following environment variables:
 //! - `AWS_WEB_IDENTITY_TOKEN_FILE`: **required**, location to find the token file containing a JWT token
 //! - `AWS_ROLE_ARN`: **required**, role ARN to assume
 //! - `AWS_IAM_ROLE_SESSION_NAME`: **optional**: Session name to use when assuming the role
 //!
-//! ## Via Shared Config Profiles
+//! ## AWS Profile Configuration
+//! **Note:** Configuration of the web identity token provider via a shared profile is only supported
+//! when using the [`ProfileFileCredentialsProvider`](crate::profile::credentials).
+//!
 //! Web identity token credentials can be loaded from `~/.aws/config` in two ways:
 //! 1. Directly:
 //!   ```ini
@@ -34,19 +45,21 @@
 //!   web_identity_token_file = /token.jwt
 //!   ```
 //!
-//! # Example
-//! Web Identity Token providers are part of the [default chain](crate::default_provider::credentials),
-//! however, you can construct one explicitly if you don't want to use the default provider chain:
+//! # Examples
+//! Web Identity Token providers are part of the [default chain](crate::default_provider::credentials).
+//! However, they may be directly constructed if you don't want to use the default provider chain.
+//! Unless overridden with [`static_configuration`](Builder::static_configuration), the provider will
+//! load configuration from environment variables.
 //!
-/// ```rust
-/// # async fn test() {
-/// use aws_config::web_identity_token::WebIdentityTokenCredentialsProvider;
-/// use aws_config::provider_config::ProviderConfig;
-/// let provider = WebIdentityTokenCredentialsProvider::builder()
-///     .configure(&ProviderConfig::with_default_region().await)
-///     .build();
-/// # }
-/// ```
+//! ```rust
+//! # async fn test() {
+//! use aws_config::web_identity_token::WebIdentityTokenCredentialsProvider;
+//! use aws_config::provider_config::ProviderConfig;
+//! let provider = WebIdentityTokenCredentialsProvider::builder()
+//!     .configure(&ProviderConfig::with_default_region().await)
+//!     .build();
+//! # }
+//! ```
 use aws_sdk_sts::Region;
 use aws_types::os_shim_internal::{Env, Fs};
 
@@ -164,7 +177,7 @@ pub struct Builder {
 impl Builder {
     /// Configure generic options of the [WebIdentityTokenCredentialsProvider]
     ///
-    /// # Example
+    /// # Examples
     /// ```rust
     /// # async fn test() {
     /// use aws_config::web_identity_token::WebIdentityTokenCredentialsProvider;