Unverified Commit 8ef985ec authored by John DiSanti's avatar John DiSanti Committed by GitHub
Browse files

Improve error doc comments around logging errors (#1990)

parent 044ebeac

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/error/CombinedErrorGenerator.kt

+2 −1
Original line number Diff line number Diff line
@@ -21,6 +21,7 @@ import software.amazon.smithy.rust.codegen.core.rustlang.Visibility 
import software.amazon.smithy.rust.codegen.core.rustlang.Writable

import software.amazon.smithy.rust.codegen.core.rustlang.asType

import software.amazon.smithy.rust.codegen.core.rustlang.deprecatedShape

import software.amazon.smithy.rust.codegen.core.rustlang.docs

import software.amazon.smithy.rust.codegen.core.rustlang.documentShape

import software.amazon.smithy.rust.codegen.core.rustlang.rust

import software.amazon.smithy.rust.codegen.core.rustlang.rustBlock
@@ -175,9 +176,9 @@ class CombinedErrorGenerator( 
                val errorVariantSymbol = symbolProvider.toSymbol(errorVariant)

                write("${errorVariantSymbol.name}(#T),", errorVariantSymbol)

            }

            docs(UNHANDLED_ERROR_DOCS)

            rust(

                """

                /// An unexpected error, e.g. invalid JSON returned by the service or an unknown error code

                Unhandled(#T),

                """,

                unhandledError(),

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/error/TopLevelErrorGenerator.kt

+2 −1
Original line number Diff line number Diff line
@@ -16,6 +16,7 @@ import software.amazon.smithy.rust.codegen.core.rustlang.RustWriter 
import software.amazon.smithy.rust.codegen.core.rustlang.Visibility

import software.amazon.smithy.rust.codegen.core.rustlang.asType

import software.amazon.smithy.rust.codegen.core.rustlang.deprecatedShape

import software.amazon.smithy.rust.codegen.core.rustlang.docs

import software.amazon.smithy.rust.codegen.core.rustlang.documentShape

import software.amazon.smithy.rust.codegen.core.rustlang.rust

import software.amazon.smithy.rust.codegen.core.rustlang.rustBlock
@@ -147,7 +148,7 @@ class TopLevelErrorGenerator(private val codegenContext: CodegenContext, private 
                val sym = symbolProvider.toSymbol(error)

                rust("${sym.name}(#T),", sym)

            }

            rust("/// An unhandled error occurred.")

            docs(UNHANDLED_ERROR_DOCS)

            rust("Unhandled(#T)", unhandledError())

        }

    }

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/error/UnhandledErrorGenerator.kt

+11 −7
Original line number Diff line number Diff line
@@ -10,14 +10,18 @@ import software.amazon.smithy.rust.codegen.core.rustlang.docs 
import software.amazon.smithy.rust.codegen.core.rustlang.rustTemplate

import software.amazon.smithy.rust.codegen.core.smithy.RuntimeType



internal fun unhandledError(): RuntimeType = RuntimeType.forInlineFun("Unhandled", RustModule.Error) {

    docs(

internal const val UNHANDLED_ERROR_DOCS =

    """

        An unexpected error occurred (e.g., invalid JSON returned by the service or an unknown error code)

    An unexpected error occurred (e.g., invalid JSON returned by the service or an unknown error code).



        Call [`Error::source`](std::error::Error::source) for more details about the underlying cause.

        """,

    )

    When logging an error from the SDK, it is recommended that you either wrap the error in

    [`DisplayErrorContext`](crate::types::DisplayErrorContext), use another

    error reporter library that visits the error's cause/source chain, or call

    [`Error::source`](std::error::Error::source) for more details about the underlying cause.

    """



internal fun unhandledError(): RuntimeType = RuntimeType.forInlineFun("Unhandled", RustModule.Error) {

    docs(UNHANDLED_ERROR_DOCS)

    rustTemplate(

        """

        ##[derive(Debug)]

rust-runtime/aws-smithy-http/src/result.rs

+5 −0
Original line number Diff line number Diff line
@@ -131,6 +131,11 @@ pub trait CreateUnhandledError { 
}



/// Failed SDK Result

///

/// When logging an error from the SDK, it is recommended that you either wrap the error in

/// [`DisplayErrorContext`](aws_smithy_types::error::display::DisplayErrorContext), use another

/// error reporter library that visits the error's cause/source chain, or call

/// [`Error::source`](std::error::Error::source) for more details about the underlying cause.

#[non_exhaustive]

#[derive(Debug)]

pub enum SdkError<E, R = operation::Response> {

rust-runtime/aws-smithy-types/src/error/display.rs

+8 −0
Original line number Diff line number Diff line
@@ -14,6 +14,14 @@ use std::fmt; 
/// in the chain separated by ": ". At the end of the chain, it outputs a debug view

/// of the entire error chain.

///

/// # Example

///

/// ```no_run

/// # let err: &dyn std::error::Error = unimplemented!();

/// # use aws_smithy_types::error::display::DisplayErrorContext;

/// println!("There was an unhandled error: {}", DisplayErrorContext(&err));

/// ```

///

// Internally in the SDK, this is useful for emitting errors with `tracing` in cases

// where the error is not returned back to the customer.

#[derive(Debug)]