Stabilize doc_cfg feature #79263

GuillaumeGomez · 2020-11-21T13:12:26Z

cc @Nemo157
cc @dtolnay
cc @rust-lang/rustdoc

rust-log-analyzer · 2020-11-21T13:15:11Z

The job mingw-check of your PR failed (pretty log, raw log). Through arcane magic we have determined that the following fragments from the build log may contain information about the problem.

Click to expand the log.

[command]/usr/bin/git submodule foreach --recursive git config --local --name-only --get-regexp 'http\.https\:\/\/github\.com\/\.extraheader' && git config --local --unset-all 'http.https://github.com/.extraheader' || :
[command]/usr/bin/git config --local http.https://github.com/.extraheader AUTHORIZATION: basic ***
##[endgroup]
##[group]Fetching the repository
[command]/usr/bin/git -c protocol.version=2 fetch --no-tags --prune --progress --no-recurse-submodules --depth=2 origin +8390e2cf97dedbc142df480388bd403520839b89:refs/remotes/pull/79263/merge
---
   Compiling libc v0.2.79
   Compiling std v0.0.0 (/checkout/library/std)
   Compiling compiler_builtins v0.1.36
   Compiling unwind v0.0.0 (/checkout/library/unwind)
error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#2)
10 | / macro_rules! int_module {
10 | / macro_rules! int_module {
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.
15 |   Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead.
...
...
28 |               pub const MIN: $T = $T::MIN;
   | |_________- in this macro invocation (#2)
...
48 | |     )
49 | | }
49 | | }
   | |_- in this expansion of `int_module!` (#1)
  ::: library/core/src/num/shells/i128.rs:10:1
   |
   |
10 |   int_module! { i128, #[stable(feature = "i128", since="1.26.0")] }
   |   ----------------------------------------------------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#2)
10 | / macro_rules! int_module {
10 | / macro_rules! int_module {
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
12 | |     ($T:ident, #[$attr:meta]) => (
13 | |         doc_comment! {
31 | /         doc_comment! {
31 | /         doc_comment! {
32 |               concat!("The largest value that can be represented by this integer type.
33 |   Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead.
...
...
46 |               pub const MAX: $T = $T::MAX;
   | |_________- in this macro invocation (#2)
48 | |     )
49 | | }
49 | | }
   | |_- in this expansion of `int_module!` (#1)
  ::: library/core/src/num/shells/i128.rs:10:1
   |
   |
10 |   int_module! { i128, #[stable(feature = "i128", since="1.26.0")] }
   |   ----------------------------------------------------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.
15 |   Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead.
...
...
28 |               pub const MIN: $T = $T::MIN;
   | |_________- in this macro invocation (#3)
...
48 | |     )
49 | | }
49 | | }
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i16.rs:10:1
   |
   |
10 |   int_module! { i16 }
   |   ------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 | |         doc_comment! {
31 | /         doc_comment! {
31 | /         doc_comment! {
32 |               concat!("The largest value that can be represented by this integer type.
33 |   Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead.
...
...
46 |               pub const MAX: $T = $T::MAX;
   | |_________- in this macro invocation (#3)
48 | |     )
49 | | }
   | | -
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i16.rs:10:1
   |
   |
10 |   int_module! { i16 }
   |   ------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.
15 |   Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead.
...
...
28 |               pub const MIN: $T = $T::MIN;
   | |_________- in this macro invocation (#3)
...
48 | |     )
49 | | }
49 | | }
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i32.rs:10:1
   |
   |
10 |   int_module! { i32 }
   |   ------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 | |         doc_comment! {
31 | /         doc_comment! {
31 | /         doc_comment! {
32 |               concat!("The largest value that can be represented by this integer type.
33 |   Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead.
...
...
46 |               pub const MAX: $T = $T::MAX;
   | |_________- in this macro invocation (#3)
48 | |     )
49 | | }
   | | -
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i32.rs:10:1
   |
   |
10 |   int_module! { i32 }
   |   ------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.
15 |   Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead.
...
...
28 |               pub const MIN: $T = $T::MIN;
   | |_________- in this macro invocation (#3)
...
48 | |     )
49 | | }
49 | | }
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i64.rs:10:1
   |
   |
10 |   int_module! { i64 }
   |   ------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 | |         doc_comment! {
31 | /         doc_comment! {
31 | /         doc_comment! {
32 |               concat!("The largest value that can be represented by this integer type.
33 |   Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead.
...
...
46 |               pub const MAX: $T = $T::MAX;
   | |_________- in this macro invocation (#3)
48 | |     )
49 | | }
   | | -
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i64.rs:10:1
   |
   |
10 |   int_module! { i64 }
   |   ------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.
15 |   Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead.
...
...
28 |               pub const MIN: $T = $T::MIN;
   | |_________- in this macro invocation (#3)
...
48 | |     )
49 | | }
49 | | }
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i8.rs:10:1
   |
   |
10 |   int_module! { i8 }
   |   ------------------ in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 | |         doc_comment! {
31 | /         doc_comment! {
31 | /         doc_comment! {
32 |               concat!("The largest value that can be represented by this integer type.
33 |   Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead.
...
...
46 |               pub const MAX: $T = $T::MAX;
   | |_________- in this macro invocation (#3)
48 | |     )
49 | | }
   | | -
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/i8.rs:10:1
   |
   |
10 |   int_module! { i8 }
   |   ------------------ in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.
15 |   Use [`", stringify!($T), "::MIN", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MIN) instead.
...
...
28 |               pub const MIN: $T = $T::MIN;
   | |_________- in this macro invocation (#3)
...
48 | |     )
49 | | }
49 | | }
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/isize.rs:10:1
   |
   |
10 |   int_module! { isize }
   |   --------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#3)
10 |   macro_rules! int_module {
   |  _-
   | |_|
   | |
   | |
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
   | |                    --------------------------------------------------------------- in this macro invocation (#2)
12 | |     ($T:ident, #[$attr:meta]) => (
13 | |         doc_comment! {
31 | /         doc_comment! {
31 | /         doc_comment! {
32 |               concat!("The largest value that can be represented by this integer type.
33 |   Use [`", stringify!($T), "::MAX", "`](../../std/primitive.", stringify!($T), ".html#associatedconstant.MAX) instead.
...
...
46 |               pub const MAX: $T = $T::MAX;
   | |_________- in this macro invocation (#3)
48 | |     )
49 | | }
   | | -
   | | -
   | |_|
   | |_in this expansion of `int_module!` (#1)
   |   in this expansion of `int_module!` (#2)
  ::: library/core/src/num/shells/isize.rs:10:1
   |
   |
10 |   int_module! { isize }
   |   --------------------- in this macro invocation (#1)

error: unexpected token: `(/*ERROR*/)`
   |
3  | / macro_rules! doc_comment {
3  | / macro_rules! doc_comment {
4  | |     ($x:expr, $($tt:tt)*) => {
5  | |         #[doc = $x]
   | |                 ^^
6  | |         $($tt)*
8  | | }
8  | | }
   | |_- in this expansion of `doc_comment!` (#2)
10 | / macro_rules! int_module {
10 | / macro_rules! int_module {
11 | |     ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]););
12 | |     ($T:ident, #[$attr:meta]) => (
13 |           doc_comment! {
   |  _________-
14 |               concat!("The smallest value that can be represented by this integer type.

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 @rust-lang/infra. (Feature Requests)

jyn514 · 2020-11-21T13:15:38Z

I think @Nemo157 is still working on some improvements to this - in particular, they're going to make it enabled by default whenever you use cfg(...), so you don't have to write both cfg and doc(cfg). I think we should wait until that happens before stabilizing.

GuillaumeGomez · 2020-11-21T14:47:04Z

Then definitely (that would be so awesome!). Keeping this PR open in the meantime so no one else is tempted to open another one (including me hehe).

Nemo157 · 2020-11-21T20:43:05Z

Yeah, I'll try to get the PR to look at that up tomorrow. It'll probably need some testing with popular libraries and feedback whether it's a net positive (I was initially against it in the discussion on the tracking issue because I thought it would run into too many internal details, but with the ability to override the documented cfg like I have implemented it I think it might be plausible).

Nemo157 · 2020-12-09T10:58:08Z

One thing I'm still slightly wary about is

doctests will only run on the appropriate platforms

Because most (all?) non-std users of this have been gating it to only run while building docs on docs.rs I don't know whether we know how this will affect them; it seems likely that this will result in some doctests silently not running. And personally what I need is the ability to gate individual doctests based on cfgs, not all doctests for a single item.

jyn514 · 2020-12-09T12:28:51Z

doctests will only run on the appropriate platforms

Could we change the standard library to use cfg_attr(predicate, doc(include)) or something like that? Then we can turn this off in rustdoc and have doc_cfg only do one thing.

jhpratt · 2020-12-22T07:07:23Z

For the curious: it looks like #79341 is the PR to make #[doc(cfg(…))] implied.

bors · 2021-04-02T09:31:25Z

☔ The latest upstream changes (presumably #80965) made this pull request unmergeable. Please resolve the merge conflicts.

jyn514 · 2021-08-16T05:30:46Z

I'm going to close this until we implement cfg implying doc(cfg).

passcod · 2022-04-11T20:11:41Z

Given #89596 was merged, should this be re-opened?

GuillaumeGomez · 2022-05-23T14:10:40Z

I think #90497 is a blocker for it.

EDIT: nevermind, it should be ready now.

LoganDark · 2022-06-22T06:59:03Z

EDIT: nevermind, it should be ready now.

Do you have an ETA for the new attempt at stabilizing doc_cfg? One of my new crates has some experimental things that are only available with a cargo feature.

GuillaumeGomez · 2022-08-22T16:01:28Z

I opened #100883.

Stabilize doc_cfg feature

1f8a3aa

rust-highfive assigned jyn514 Nov 21, 2020

rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Nov 21, 2020

jyn514 added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Nov 21, 2020

jyn514 added S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Nov 21, 2020

jyn514 added the F-doc_cfg `#![feature(doc_cfg)]` label Nov 21, 2020

camelid added S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. and removed S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. labels Mar 12, 2021

jyn514 mentioned this pull request Apr 22, 2021

Tracking issue for #[doc(cfg(…))], #[doc(cfg_hide(…))] and doc_auto_cfg #43781

Open

4 tasks

camelid added S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. and removed S-blocked Status: Marked as blocked ❌ on something else such as an RFC or other implementation work. labels May 28, 2021

jonas-schievink added the relnotes Marks issues that should be documented in the release notes of the next release. label Jul 17, 2021

jyn514 closed this Aug 16, 2021

GuillaumeGomez deleted the stabilize-doc-cfg branch August 16, 2021 09:53

GuillaumeGomez restored the stabilize-doc-cfg branch August 22, 2022 15:07

GuillaumeGomez mentioned this pull request Aug 22, 2022

Stabilize doc_cfg, auto_doc_cfg and cfg_hide features #100883

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Stabilize doc_cfg feature #79263

Stabilize doc_cfg feature #79263

GuillaumeGomez commented Nov 21, 2020 •

edited

Loading

rust-log-analyzer commented Nov 21, 2020

jyn514 commented Nov 21, 2020

GuillaumeGomez commented Nov 21, 2020

Nemo157 commented Nov 21, 2020

Nemo157 commented Dec 9, 2020

jyn514 commented Dec 9, 2020

jhpratt commented Dec 22, 2020

bors commented Apr 2, 2021

jyn514 commented Aug 16, 2021

passcod commented Apr 11, 2022

GuillaumeGomez commented May 23, 2022 •

edited

Loading

LoganDark commented Jun 22, 2022 •

edited

Loading

GuillaumeGomez commented Aug 22, 2022

Stabilize doc_cfg feature #79263

Stabilize doc_cfg feature #79263

Conversation

GuillaumeGomez commented Nov 21, 2020 • edited Loading

rust-log-analyzer commented Nov 21, 2020

jyn514 commented Nov 21, 2020

GuillaumeGomez commented Nov 21, 2020

Nemo157 commented Nov 21, 2020

Nemo157 commented Dec 9, 2020

jyn514 commented Dec 9, 2020

jhpratt commented Dec 22, 2020

bors commented Apr 2, 2021

jyn514 commented Aug 16, 2021

passcod commented Apr 11, 2022

GuillaumeGomez commented May 23, 2022 • edited Loading

LoganDark commented Jun 22, 2022 • edited Loading

GuillaumeGomez commented Aug 22, 2022

GuillaumeGomez commented Nov 21, 2020 •

edited

Loading

GuillaumeGomez commented May 23, 2022 •

edited

Loading

LoganDark commented Jun 22, 2022 •

edited

Loading