Repository: rustls/rustls (language: rust)

Issue:
discussion: re-exporting rustls-pki-types
Pulling out a conversation from https://github.com/rustls/rustls/pull/1651#issuecomment-1836814664:

> One question I've had is if we should be re-exporting the pki-types, maybe as rustls::types? I think that would make life a bit easier? We could do the same across some of the other crates, I suppose.

My feeling is no. We can document that rustls depends on pki-types 1.0, but I think the pattern of re-exporting a crate in multiple places is confusing.

One of my very confusing experiences as a Rust beginner was noticing that [`hyper::Response`](https://docs.rs/hyper/latest/hyper/struct.Request.html) and [`http::Response`](https://docs.rs/http/latest/http/request/struct.Request.html) have the same documentation, the same methods, and so on, but are in different libraries. It's not documented that one is actually a re-export of the other, so I thought it might have been copy-pasted code or an older version of the same library. I wound up spending some time looking carefully for differences to see why these were different types, and of course found none.


Discussion / hints:
Fair enough. I agree the documentation situation for re-exports is pretty weak, but I like using them in practice -- avoiding the extra import and (hopefully not much in this case, but in many other situations) the coupled version tracking. Maybe this needs a rustdoc feature to clearly highlight re-exports? Would be a nice to have IMO.
I quite like reexports, and think they work well if
- used sparingly,
- they're dependencies that are absolutely required for 99% of uses of  the "primary" crate. I think pki-types satisfies that; but not (eg) webpki.
- are kept "flat", eg. in some crate there are a large number of transitive reexports of lower-level crates (which also reexport their dependencies) which is a bit much. It leads to things like the `rsa` crate transitively reexporting `rand_core` many times through the reexports of all its dependencies.
> they're dependencies that are absolutely required for 99% of uses of the "primary" crate. I think pki-types satisfies that; but not (eg) webpki.

Having done a few dependent crate updates at this point I agree with this assessment RE: pki-types. The dependent crates I've been updating don't use pki-types anywhere except for interacting with rustls. Having to carry and version an independent dependency on pki-types feels like noise that could be cut out with a re-export.
Reopening discussion to consider https://github.com/rustls/pki-types/pull/24.

Also I wanted to note (and this is clearly a rustdoc bug): the rustls re-exports will show `Available on crate feature alloc only` for some items like `CertificateDer::into_owned`, even though `rustls` doesn't have a crate feature `alloc`.
> Also I wanted to note (and this is clearly a rustdoc bug): the rustls re-exports will show `Available on crate feature alloc only` for some items like `CertificateDer::into_owned`, even though `rustls` doesn't have a crate feature `alloc`.

Should we file for this?

Why is it useful to reopen this issue rather than discussing on the PR itself?

Fix patch:
diff --git a/rustls/src/lib.rs b/rustls/src/lib.rs
index f9e2c8533fd..05356279e8f 100644
--- a/rustls/src/lib.rs
+++ b/rustls/src/lib.rs
@@ -637,6 +637,7 @@ pub mod version {
 
 /// Re-exports the contents of the [rustls-pki-types](https://docs.rs/rustls-pki-types) crate for easy access
 pub mod pki_types {
+    #[doc(no_inline)]
     pub use pki_types::*;
 }
 


Test patch: