async-rs / async-rs/async-std

Document re-exports better

Open
#566 1 comment 1 reaction 0 assignees View on GitHub
documentation
Dominant language
Rust
Stars
4.1k
Forks
339
PR merge metrics
No merged PRs in 30d

Description

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:

```rust
#[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

![Screenshot_2019-11-20 async_std task - Rust(1)](https://user-images.githubusercontent.com/2467194/69237567-3cb95400-0b96-11ea-898b-9ba359c07104.png)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.