Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve builder method documentation #891

Open
Velfi opened this issue Nov 23, 2021 · 0 comments
Open

Improve builder method documentation #891

Velfi opened this issue Nov 23, 2021 · 0 comments
Labels
documentation Improvements or additions to documentation sdk

Comments

@Velfi
Copy link
Contributor

Velfi commented Nov 23, 2021

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;
        /// # }
        /// ```
        pub fn retry_config(mut self, 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;
        /// # }
        /// ```
        pub fn timeout_config(mut self, 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

@rcoh rcoh added the documentation Improvements or additions to documentation label Nov 23, 2021
@jdisanti jdisanti added the sdk label Sep 30, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation sdk
Projects
None yet
Development

No branches or pull requests

3 participants