diff --git a/docs/rust/introduction.md b/docs/rust/introduction.md index aa129767ba72..39fa63089172 100644 --- a/docs/rust/introduction.md +++ b/docs/rust/introduction.md @@ -648,7 +648,7 @@ The `azure_core` package provides common functionality for client libraries. Doc ### Errors {#rust-errors} -{% include requirement/MUST id="rust-errors-core" %} return an `azure_core::Result` which uses `azure_core::Error`. +{% include requirement/MUST id="rust-errors-core" %} return or convert into an `azure_core::Result` which uses `azure_core::Error`. {% include requirement/MUST id="rust-errors-core-methods" %} call appropriate methods on `azure_core::Error` to wrap or otherwise convert to an appropriate `azure_core::ErrorKind`. @@ -679,6 +679,18 @@ impl Into for Error { } ``` +### Crate-specific errors {#rust-errors-crate} + +{% include requirement/MAY id="rust-errors-crate-specific" %} return a crate-specific `Error` and `Result` if they must expose more specific information appropriate for their domain to the callers. + +If you define a crate-specific `Error`, + +{% include requirement/MUST id="rust-errors-crate-definitions" %} define your `Error`, `Result`, `ErrorKind`, and other types like `azure_core` so that all types are exported from `crate::error`, and `Error` and `Result` are exported from the root module. + +{% include requirement/MUST id="rust-errors-crate-into-core" %} implement `From for azure_core::Error` to convert your error into an `azure_core::Error`. If there is no other appropriate `azure_core::error::ErrorKind`, use `ErrorKind::Other`. This ensures callers can use the `?` operator in their own functions that might return an `azure_core::Result`. + +{% include requirement/MUST id="rust-errors-crate-from-core" %} implement `From for crate::Error` to convert an `azure_core::Error` into your error. This ensures you can use the `?` operator with `azure_core` functions that return an `azure_core::Result`. + ### Authentication {#rust-authentication} Azure services use a variety of different authentication schemes to allow clients to access the service. Conceptually, there are two entities responsible in this process: a credential and an authentication policy. Credentials provide confidential authentication data. Authentication policies use the data provided by a credential to authenticate requests to the service.