You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Our current builder method documentation can be very terse and doesn't leave a breadcrumb trail for curious users to follow. Let's look at an example drawn from aws_config::ConfigLoader:
/// Override the retry_config used to build [`Config`](aws_types::config::Config).////// # Examples/// ```rust/// # use aws_smithy_types::retry::RetryConfig;/// # async fn create_config() {/// let config = aws_config::from_env()/// .retry_config(RetryConfig::new().with_max_attempts(2))/// .load().await;/// # }/// ```pubfnretry_config(mutself,retry_config:RetryConfig) -> Self{self.retry_config = Some(retry_config);self}/// Override the timeout config used to build [`Config`](aws_types::config::Config)./// **Note: This only sets timeouts for calls to AWS services.** Timeouts for the credentials/// provider chain are configured separately.////// # Examples/// ```rust/// # use std::time::Duration;/// # use aws_smithy_types::timeout::TimeoutConfig;/// # async fn create_config() {/// let timeout_config = TimeoutConfig::new().with_api_call_timeout(Some(Duration::from_secs(1)));/// let config = aws_config::from_env()/// .timeout_config(timeout_config)/// .load()/// .await;/// # }/// ```pubfntimeout_config(mutself,timeout_config:TimeoutConfig) -> Self{self.timeout_config = Some(timeout_config);self}
Both of these doc comments provide an example and that's great, but they don't link to the definitions of RetryConfig or TimeoutConfig. Nor do they direct users to documentation that would help users understand when and why to set these things.
I think that we should avoid copy-pasting docs but I do think that we have an opportunity to provide a more convenient interlinking between docs
The text was updated successfully, but these errors were encountered:
Our current builder method documentation can be very terse and doesn't leave a breadcrumb trail for curious users to follow. Let's look at an example drawn from
aws_config::ConfigLoader
:Both of these doc comments provide an example and that's great, but they don't link to the definitions of
RetryConfig
orTimeoutConfig
. Nor do they direct users to documentation that would help users understand when and why to set these things.I think that we should avoid copy-pasting docs but I do think that we have an opportunity to provide a more convenient interlinking between docs
The text was updated successfully, but these errors were encountered: