[rustdoc] stabilize cfg(doctest)#63803
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
There was a problem hiding this comment.
Since we're stabilizing this, I think the note here about features should be removed, right?
There was a problem hiding this comment.
Maybe something like "either make items conditionally public via cfg(doctest) or write a unit test"?
There was a problem hiding this comment.
I would avoid the "collecting" language I think -- maybe "when compiling a crate for use in doctests, rustdoc will set cfg(doctest).
There was a problem hiding this comment.
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 fooWith //! 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.