Merge rust-bitcoin/rust-bitcoin#2520: policy: Introduce error type re-export policy

7de02da9f5 policy: Introduce error type re-export policy (Tobin C. Harding)

Pull request description:

  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.

ACKs for top commit:
  apoelstra:
    ACK 7de02da9f5 LGTM

Tree-SHA512: 42b9d9b78c882d39553c3d72c188d80f5e305e1f7f1b9b9212760c75ff35ea71e868c93a17851ca0bf2104b01d5c6d316cd14c422c262ff39ad72922c562af4a

CONTRIBUTING.md

@@ -338,6 +338,8 @@ internals::impl_from_infallible!(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