Document re-exports better

[yoshuawuyts]

We use #[doc(inline)] for std and futures re-exports; this is nice because it creates a more cohesive feel for our library (which makes it easier to discover and learn). But it can sometimes be confusing for people what we re-export, and what not.

One way we could do this is by writing docs for all our re-exports, and what we've newly defined in each mod-level docs. This might be useful to create a distinction:

• re-exports: what did we re-export from std or futures?
• ports: what did we 1:1 port from std, and just make async?
• new: what did we newly define that has no counterpart in std?

Additionally we could mark direct re-exports such as task::Context with a label in our documentation to show that they've been re-exported:

#[cfg_attr(feature = "docs", doc(cfg(re-export)))]

Though I'm unsure how good this is, as it would take the same place as "unstable" and could be confusing to people. But still, it's probably something worth considering.

Thanks!

Screenshots

[abalmos]

My two cents:

This is important with the current state of fraction between rust async solutions. While working on compat layers between async-std and tokio (because tokio is still pondering adopting some of the futures 0.3 traits), I kept going down rabbits holes not realizing that something was a simple a re-export of std or futures. I think async-std should be celebrating that it doesn't feel the need to re-implement everything.

If re-exports are to stay (rather then just asking people to use the original traits directly) then I think the docs should very clearly indicate what is and what is not a re-export (a port vs new is also useful to know). I believe this is best done with some simple, consistent doc text across the library. The re-export label sounds like a decent solution, but I feel it renders too noisy.

Side thought: Ideally docs.rs would just automatically annotate the doc page of a trait/struct as a re-export. The current list of re-exports that it generates isn't that useful.