Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Improve docs for tokio_unstable. #4524

Merged
merged 7 commits into from Feb 25, 2022
Merged

Improve docs for tokio_unstable. #4524

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
435a82f
Improve docs for tokio_unstable.
NfNitLoop Feb 21, 2022
40c16ee
Enable --cfg tokio_unstable on FreeBSD doc builds.
NfNitLoop Feb 22, 2022
6fe802b
Also --cfg unstable_tokio for ci.yml doc builds.
NfNitLoop Feb 22, 2022
6498722
Fix: --cfg tokio_unstable. >.<
NfNitLoop Feb 22, 2022
84d343d
Doc task::Builder as an unstable API.
NfNitLoop Feb 23, 2022
d351453
Run rustfmt.
NfNitLoop Feb 23, 2022
0333451
Add examples of setting environment variables.
NfNitLoop Feb 24, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
4 changes: 2 additions & 2 deletions .cirrus.yml
View file
Open in desktop
Expand Up @@ -26,8 +26,8 @@ task:
task:
name: FreeBSD docs
env:
RUSTFLAGS: --cfg docsrs
RUSTDOCFLAGS: --cfg docsrs -Dwarnings
RUSTFLAGS: --cfg docsrs --cfg tokio_unstable
RUSTDOCFLAGS: --cfg docsrs --cfg tokio_unstable -Dwarnings
setup_script:
- pkg install -y bash curl
- curl https://sh.rustup.rs -sSf --output rustup.sh
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
View file
Open in desktop
Expand Up @@ -360,7 +360,7 @@ jobs:
run: cargo doc --lib --no-deps --all-features --document-private-items
env:
RUSTFLAGS: --cfg docsrs
RUSTDOCFLAGS: --cfg docsrs -Dwarnings
RUSTDOCFLAGS: --cfg docsrs --cfg unstable_tokio -Dwarnings
Darksonn marked this conversation as resolved.
Show resolved Hide resolved

loom-compile:
name: build loom tests
Expand Down
30 changes: 24 additions & 6 deletions tokio/src/lib.rs
View file
Open in desktop
Expand Up @@ -339,14 +339,32 @@
//! _parking_lot_ release in use.
//!
//! ### Unstable features
//!
//! These feature flags enable **unstable** features. The public API may break in 1.x
//! releases. To enable these features, the `--cfg tokio_unstable` must be passed to
//! `rustc` when compiling. This is easiest done using the `RUSTFLAGS` env variable:
//! `RUSTFLAGS="--cfg tokio_unstable"`.
//!
//!
//! Some feature flags are only available when specifying the `tokio_unstable` flag:
//!
//! - `tracing`: Enables tracing events.
//!
//! Likewise, some parts of the API are only available with the same flag:
//!
//! - [`task::JoinSet`]
Darksonn marked this conversation as resolved.
Show resolved Hide resolved
//!
//! This flag enables **unstable** features. The public API of these features
//! may break in 1.x releases.
//!
//! To enable these features, the `--cfg tokio_unstable` must be passed to
//! `rustc` when compiling. This is easiest done using the `RUSTFLAGS` env
//! variable: `RUSTFLAGS="--cfg tokio_unstable"`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably show a full invocation to cargo build. Preferably for both unix and windows if different.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This blurb was previously existing (from 79d25b0) and just got reformatted with my changes. I just left it in as-is.

I'm wary about trying to explain how to use environment variables and cargo build on various systems, though. (For example, on Windows it's different depending on whether you're using the command prompt or PowerShell. Not to mention the various *nix shells.)

Copy link
Contributor

@Darksonn Darksonn Feb 23, 2022 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You don't have to document every possible shell out there, but I still think that including some common variants is useful. I suspect that many people will not know how to specify environment variables.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OK, added *nix + Windows PowerShell examples.

//!
//! You can also specify it in your project's `.cargo/config.toml` file:
//!
//! ```toml
//! [build]
//! rustflags = ["--cfg", "tokio_unstable"]
//! ```
//! This serves to explicitly opt-in to features which may break semver conventions,
//! since Cargo [does not yet directly support such opt-ins][unstable features].
//!
//! [unstable features]: https://internals.rust-lang.org/t/feature-request-unstable-opt-in-non-transitive-crate-features/16193#why-not-a-crate-feature-2
//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section

// Test that pointer width is compatible. This asserts that e.g. usize is at
Expand Down