-
Notifications
You must be signed in to change notification settings - Fork 13.4k
[rustdoc] stabilize cfg(doctest) #63803
New issue
Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? # to your account
Conversation
8946805
to
2e000c0
Compare
The job Click to expand the log.
I'm a bot! I can only do what humans tell me to, so if this was not helpful or you have suggestions for improvements, please ping or otherwise contact |
Does it make sense to open a PR before the discussion mentioned at #62210 (comment) has been had? |
@RalfJung We already validated to stabilize |
Oh and I fixed the failure, just waiting for github to update the display I guess... |
@GuillaumeGomez do you have pointers to that discussion? |
9472a47
to
0f91e98
Compare
Isn't the issue description enough? And the fact that we stabilized the |
☔ The latest upstream changes (presumably #63824) made this pull request unmergeable. Please resolve the merge conflicts. |
Ping from triage. @GuillaumeGomez any progress? |
Need to fix conflict (again) but beside that I'm waiting for someone to approve. |
b859350
to
116185e
Compare
collecting doctests, so you can utilize doctest functionality without forcing the test to appear in | ||
docs, or to find an arbitrary private item to include it on. | ||
|
||
If you add `#![feature(cfg_doctest)]` to your crate, Rustdoc will set `cfg(doctest)` when collecting |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Since we're stabilizing this, I think the note here about features should be removed, right?
|
||
If you add `#![feature(cfg_doctest)]` to your crate, Rustdoc will set `cfg(doctest)` when collecting | ||
doctests. Note that they will still link against only the public items of your crate; if you need to | ||
test private items, unit tests are still the way to go. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe something like "either make items conditionally public via cfg(doctest)
or write a unit test"?
collecting doctests, so you can utilize doctest functionality without forcing the test to appear in | ||
docs, or to find an arbitrary private item to include it on. | ||
|
||
If you add `#![feature(cfg_doctest)]` to your crate, Rustdoc will set `cfg(doctest)` when collecting |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would avoid the "collecting" language I think -- maybe "when compiling a crate for use in doctests, rustdoc will set cfg(doctest)
.
/// let x = my_crate::MyStruct(-5); | ||
/// ``` | ||
#[cfg(doctest)] | ||
pub struct MyStructOnlyTakesUsize; |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It would be good to add a note somewhere that this struct isn't actually exposed in anyway, i.e., it won't be in documentation or in the public API of this crate.
@GuillaumeGomez Let's also initiate FCP (should be I think modulo FCP this PR is good to go from a stabilization/documentation standpoint; I would like to think some more about it but I can do that async with FCP and such. |
116185e
to
1174308
Compare
I made the suggested changes. Thanks for reviewing!
Completely fine by me. Let's go for it! @rfcbot fcp merge |
The final comment period, with a disposition to merge, as per the review above, is now complete. As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed. The RFC will be merged soon. |
@bors: r=ollie27,QuietMisdreavus,Mark-Simulacrum |
📌 Commit 1595fde has been approved by |
…ietMisdreavus,Mark-Simulacrum [rustdoc] stabilize cfg(doctest) Fixes #62210. Since we removed rustdoc from providing cfg(test) on test runs, it's been replaced by cfg(doctest). It'd be nice to have it in not too far in the future.
☀️ Test successful - checks-azure |
FINALLY! |
After this PR landed, we are seeing compile failures from |
Never mind, that was just an outdated |
Am I misunderstanding how this is supposed to work? I thought it would enable me to use things in doc tests that were otherwise not included. But when I define a pub function for example and mark it with I am using cargo 1.41.0-nightly (626f0f40e 2019-12-03). I create a new library package with //! Hello
//!
//! ```
//! use crate::hello::hello;
//! hello();
//! ```
#[cfg(doctest)]
pub fn hello ()
{
println!("hello");
} When I run
|
Shouldn't it be |
@GuillaumeGomez Any which way has the same result. First, create empty lib crate. cargo init --lib foo With //! Hello
//!
//! ```
//! use crate::foo::bar;
//! bar();
//! ```
#[cfg(doctest)]
pub fn bar ()
{
println!("hello");
}
With //! Hello
//!
//! ```
//! use foo::bar;
//! bar();
//! ```
#[cfg(doctest)]
pub fn bar ()
{
println!("hello");
}
//! Hello
//!
//! ```
//! use crate::bar;
//! bar();
//! ```
#[cfg(doctest)]
pub fn bar ()
{
println!("hello");
} With
|
This isn't normal indeed. Checking what's going on. |
I created #67295 to keep track of this issue. I'm currently focused on next gtk-rs release but once done, I'll check this one and fix it. |
Excellent, thank you :) |
Version 1.40.0 (2019-12-19) =========================== Language -------- - [You can now use tuple `struct`s and tuple `enum` variant's constructors in `const` contexts.][65188] e.g. ```rust pub struct Point(i32, i32); const ORIGIN: Point = { let constructor = Point; constructor(0, 0) }; ``` - [You can now mark `struct`s, `enum`s, and `enum` variants with the `#[non_exhaustive]` attribute to indicate that there may be variants or fields added in the future.][64639] For example this requires adding a wild-card branch (`_ => {}`) to any match statements on a non-exhaustive `enum`. [(RFC 2008)] - [You can now use function-like procedural macros in `extern` blocks and in type positions.][63931] e.g. `type Generated = macro!();` - [Function-like and attribute procedural macros can now emit `macro_rules!` items, so you can now have your macros generate macros.][64035] - [The `meta` pattern matcher in `macro_rules!` now correctly matches the modern attribute syntax.][63674] For example `(#[$m:meta])` now matches `#[attr]`, `#[attr{tokens}]`, `#[attr[tokens]]`, and `#[attr(tokens)]`. Compiler -------- - [Added tier 3 support\* for the `thumbv7neon-unknown-linux-musleabihf` target.][66103] - [Added tier 3 support for the `aarch64-unknown-none-softfloat` target.][64589] - [Added tier 3 support for the `mips64-unknown-linux-muslabi64`, and `mips64el-unknown-linux-muslabi64` targets.][65843] \* Refer to Rust's [platform support page][forge-platform-support] for more information on Rust's tiered platform support. Libraries --------- - [The `is_power_of_two` method on unsigned numeric types is now a `const` function.][65092] Stabilized APIs --------------- - [`BTreeMap::get_key_value`] - [`HashMap::get_key_value`] - [`Option::as_deref_mut`] - [`Option::as_deref`] - [`Option::flatten`] - [`UdpSocket::peer_addr`] - [`f32::to_be_bytes`] - [`f32::to_le_bytes`] - [`f32::to_ne_bytes`] - [`f64::to_be_bytes`] - [`f64::to_le_bytes`] - [`f64::to_ne_bytes`] - [`f32::from_be_bytes`] - [`f32::from_le_bytes`] - [`f32::from_ne_bytes`] - [`f64::from_be_bytes`] - [`f64::from_le_bytes`] - [`f64::from_ne_bytes`] - [`mem::take`] - [`slice::repeat`] - [`todo!`] Cargo ----- - [Cargo will now always display warnings, rather than only on fresh builds.][cargo/7450] - [Feature flags (except `--all-features`) passed to a virtual workspace will now produce an error.][cargo/7507] Previously these flags were ignored. - [You can now publish `dev-dependencies` without including a `version`.][cargo/7333] Misc ---- - [You can now specify the `#[cfg(doctest)]` attribute to include an item only when running documentation tests with `rustdoc`.][63803] Compatibility Notes ------------------- - [As previously announced, any previous NLL warnings in the 2015 edition are now hard errors.][64221] - [The `include!` macro will now warn if it failed to include the entire file.][64284] The `include!` macro unintentionally only includes the first _expression_ in a file, and this can be unintuitive. This will become either a hard error in a future release, or the behavior may be fixed to include all expressions as expected. - [Using `#[inline]` on function prototypes and consts now emits a warning under `unused_attribute` lint.][65294] Using `#[inline]` anywhere else inside traits or `extern` blocks now correctly emits a hard error. [65294]: rust-lang/rust#65294 [66103]: rust-lang/rust#66103 [65843]: rust-lang/rust#65843 [65188]: rust-lang/rust#65188 [65092]: rust-lang/rust#65092 [64589]: rust-lang/rust#64589 [64639]: rust-lang/rust#64639 [64221]: rust-lang/rust#64221 [64284]: rust-lang/rust#64284 [63931]: rust-lang/rust#63931 [64035]: rust-lang/rust#64035 [63674]: rust-lang/rust#63674 [63803]: rust-lang/rust#63803 [cargo/7450]: rust-lang/cargo#7450 [cargo/7507]: rust-lang/cargo#7507 [cargo/7525]: rust-lang/cargo#7525 [cargo/7333]: rust-lang/cargo#7333 [(rfc 2008)]: https://rust-lang.github.io/rfcs/2008-non-exhaustive.html [`f32::to_be_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.to_be_bytes [`f32::to_le_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.to_le_bytes [`f32::to_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.to_ne_bytes [`f64::to_be_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_be_bytes [`f64::to_le_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_le_bytes [`f64::to_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_ne_bytes [`f32::from_be_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.from_be_bytes [`f32::from_le_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.from_le_bytes [`f32::from_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.from_ne_bytes [`f64::from_be_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.from_be_bytes [`f64::from_le_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.from_le_bytes [`f64::from_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.from_ne_bytes [`option::flatten`]: https://doc.rust-lang.org/std/option/enum.Option.html#method.flatten [`option::as_deref`]: https://doc.rust-lang.org/std/option/enum.Option.html#method.as_deref [`option::as_deref_mut`]: https://doc.rust-lang.org/std/option/enum.Option.html#method.as_deref_mut [`hashmap::get_key_value`]: https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.get_key_value [`btreemap::get_key_value`]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html#method.get_key_value [`slice::repeat`]: https://doc.rust-lang.org/std/primitive.slice.html#method.repeat [`mem::take`]: https://doc.rust-lang.org/std/mem/fn.take.html [`udpsocket::peer_addr`]: https://doc.rust-lang.org/std/net/struct.UdpSocket.html#method.peer_addr [`todo!`]: https://doc.rust-lang.org/std/macro.todo.html
Version 1.40.0 (2019-12-19) =========================== Language -------- - [You can now use tuple `struct`s and tuple `enum` variant's constructors in `const` contexts.][65188] e.g. ```rust pub struct Point(i32, i32); const ORIGIN: Point = { let constructor = Point; constructor(0, 0) }; ``` - [You can now mark `struct`s, `enum`s, and `enum` variants with the `#[non_exhaustive]` attribute to indicate that there may be variants or fields added in the future.][64639] For example this requires adding a wild-card branch (`_ => {}`) to any match statements on a non-exhaustive `enum`. [(RFC 2008)] - [You can now use function-like procedural macros in `extern` blocks and in type positions.][63931] e.g. `type Generated = macro!();` - [Function-like and attribute procedural macros can now emit `macro_rules!` items, so you can now have your macros generate macros.][64035] - [The `meta` pattern matcher in `macro_rules!` now correctly matches the modern attribute syntax.][63674] For example `(#[$m:meta])` now matches `#[attr]`, `#[attr{tokens}]`, `#[attr[tokens]]`, and `#[attr(tokens)]`. Compiler -------- - [Added tier 3 support\* for the `thumbv7neon-unknown-linux-musleabihf` target.][66103] - [Added tier 3 support for the `aarch64-unknown-none-softfloat` target.][64589] - [Added tier 3 support for the `mips64-unknown-linux-muslabi64`, and `mips64el-unknown-linux-muslabi64` targets.][65843] \* Refer to Rust's [platform support page][forge-platform-support] for more information on Rust's tiered platform support. Libraries --------- - [The `is_power_of_two` method on unsigned numeric types is now a `const` function.][65092] Stabilized APIs --------------- - [`BTreeMap::get_key_value`] - [`HashMap::get_key_value`] - [`Option::as_deref_mut`] - [`Option::as_deref`] - [`Option::flatten`] - [`UdpSocket::peer_addr`] - [`f32::to_be_bytes`] - [`f32::to_le_bytes`] - [`f32::to_ne_bytes`] - [`f64::to_be_bytes`] - [`f64::to_le_bytes`] - [`f64::to_ne_bytes`] - [`f32::from_be_bytes`] - [`f32::from_le_bytes`] - [`f32::from_ne_bytes`] - [`f64::from_be_bytes`] - [`f64::from_le_bytes`] - [`f64::from_ne_bytes`] - [`mem::take`] - [`slice::repeat`] - [`todo!`] Cargo ----- - [Cargo will now always display warnings, rather than only on fresh builds.][cargo/7450] - [Feature flags (except `--all-features`) passed to a virtual workspace will now produce an error.][cargo/7507] Previously these flags were ignored. - [You can now publish `dev-dependencies` without including a `version`.][cargo/7333] Misc ---- - [You can now specify the `#[cfg(doctest)]` attribute to include an item only when running documentation tests with `rustdoc`.][63803] Compatibility Notes ------------------- - [As previously announced, any previous NLL warnings in the 2015 edition are now hard errors.][64221] - [The `include!` macro will now warn if it failed to include the entire file.][64284] The `include!` macro unintentionally only includes the first _expression_ in a file, and this can be unintuitive. This will become either a hard error in a future release, or the behavior may be fixed to include all expressions as expected. - [Using `#[inline]` on function prototypes and consts now emits a warning under `unused_attribute` lint.][65294] Using `#[inline]` anywhere else inside traits or `extern` blocks now correctly emits a hard error. [65294]: rust-lang/rust#65294 [66103]: rust-lang/rust#66103 [65843]: rust-lang/rust#65843 [65188]: rust-lang/rust#65188 [65092]: rust-lang/rust#65092 [64589]: rust-lang/rust#64589 [64639]: rust-lang/rust#64639 [64221]: rust-lang/rust#64221 [64284]: rust-lang/rust#64284 [63931]: rust-lang/rust#63931 [64035]: rust-lang/rust#64035 [63674]: rust-lang/rust#63674 [63803]: rust-lang/rust#63803 [cargo/7450]: rust-lang/cargo#7450 [cargo/7507]: rust-lang/cargo#7507 [cargo/7525]: rust-lang/cargo#7525 [cargo/7333]: rust-lang/cargo#7333 [(rfc 2008)]: https://rust-lang.github.io/rfcs/2008-non-exhaustive.html [`f32::to_be_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.to_be_bytes [`f32::to_le_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.to_le_bytes [`f32::to_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.to_ne_bytes [`f64::to_be_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_be_bytes [`f64::to_le_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_le_bytes [`f64::to_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.to_ne_bytes [`f32::from_be_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.from_be_bytes [`f32::from_le_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.from_le_bytes [`f32::from_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f32.html#method.from_ne_bytes [`f64::from_be_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.from_be_bytes [`f64::from_le_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.from_le_bytes [`f64::from_ne_bytes`]: https://doc.rust-lang.org/std/primitive.f64.html#method.from_ne_bytes [`option::flatten`]: https://doc.rust-lang.org/std/option/enum.Option.html#method.flatten [`option::as_deref`]: https://doc.rust-lang.org/std/option/enum.Option.html#method.as_deref [`option::as_deref_mut`]: https://doc.rust-lang.org/std/option/enum.Option.html#method.as_deref_mut [`hashmap::get_key_value`]: https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.get_key_value [`btreemap::get_key_value`]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html#method.get_key_value [`slice::repeat`]: https://doc.rust-lang.org/std/primitive.slice.html#method.repeat [`mem::take`]: https://doc.rust-lang.org/std/mem/fn.take.html [`udpsocket::peer_addr`]: https://doc.rust-lang.org/std/net/struct.UdpSocket.html#method.peer_addr [`todo!`]: https://doc.rust-lang.org/std/macro.todo.html
rust-lang/rust#63803 we'll get there, eventually
Fixes #62210.
Since we removed rustdoc from providing cfg(test) on test runs, it's been replaced by cfg(doctest). It'd be nice to have it in not too far in the future.