From 7de02da9f5f7223c08c353acd90cbe04968a9776 Mon Sep 17 00:00:00 2001 From: "Tobin C. Harding" Date: Thu, 29 Feb 2024 09:57:05 +1100 Subject: [PATCH] policy: Introduce error type re-export policy We have started introducing `error` sub-modules for modules that have a lot of error code. This is mainly a code organisation thing. When importing a function it is annoying to have to go to another module to get the returned error type. Furthermore it leaks our module structure and introduces a maintenance burden because for modules that do not [yet] have an `error` sub-module the error types are in a different place to modules that do have an `error` sub-module. Furthermore, if function users have to go to the `error` sub-module to read docs etc. they are bombarded with all the hider errors as well (see definitions below). We can solve both problems by re-exporting all regular errors, making the `error` sub-module public (for niche users), and not re-exporting hider errors. I believe the re-export should only be done in the module that holds `error` sub-module i.e., do not re-export `foo::error::SomeError` from `bar` module even if `bar::some_function` returns `SomeError`. Definitions: - hider error: An error type, often a struct, that is nested in another error just to hide the internals. - regular error: An error type that is returned from a public function, most often an enum. Please note that some times errors act as both hider errors and regular errors so the definitions are not perfect. --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 595d7d220..2d413a02c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -323,6 +323,8 @@ pub enum Error { } ``` +All errors that live in an `error` module (eg, `foo/error.rs`) and appear in a public function in +`foo` module should be available from `foo` i.e., should be re-exported from `foo/mod.rs`. #### Rustdocs