Make cfg imply doc(cfg) #79341

Nemo157 · 2020-11-23T12:39:44Z

This is only active when the doc_cfg feature is active.

The implicit cfg can be overridden via #[doc(cfg(...))], so e.g. to hide a #[cfg] you can use something like:

#[cfg(unix)]
#[doc(cfg(all()))]
pub struct Unix;

By adding #![doc(cfg_hide(foobar))] to the crate attributes the cfg #[cfg(foobar)] (and only that exact cfg) will not be implicitly treated as a doc(cfg) to render a message in the documentation.

TODO:

Test against some popular libraries, especially those already using doc(cfg)
Update doc(cfg) docs
Add doc(cfg_hide) docs

rust-highfive · 2020-11-23T12:39:47Z

r? @ollie27

(rust_highfive has picked a reviewer for you, use r? to override)

petrochenkov · 2020-11-23T13:52:30Z

Is this relying on the fact that #[cfg] expansion leaves the #[cfg] attribute in place?
Then it relies on an undocumented bug that I was actually going to fix soon.

Here's what the reference say:

If the predicate is true, the thing is rewritten to not have the cfg attribute on it.

(Which matches the intention, but not reality, because cfg currently behaves unlike any other active attribute and keeps itself during expansion.)

Nemo157 · 2020-11-23T13:55:14Z

For my own crates that use doc-cfg this works perfectly, I can remove the doc(cfg) lines and get the correct features rendered.

For tokio 0.3.4 this adds a bunch of Unix cfgs to the docs. There are a couple of cfg(not(loom)) that need suppressing, and some kind of bug to do with the cfg displayed for tokio::{main, test} that I need to look into.

For syn 1.0.50 this exposes quite a few more cfgs that seem correct, it probably needs looking at by a syn dev to see if they really should be exposed. There's also a couple WebAssembly cfgs that need suppressing.

Nemo157 · 2020-11-23T14:02:11Z

Is this relying on the fact that #[cfg] expansion leaves the #[cfg] attribute in place?

Yeah, probably. Would there be some way to look back at the original AST and see what #[cfg] were applied to a specific node if they get removed? Or could rustdoc run some pass before #[cfg] expansion to save this off into a side-table?

petrochenkov · 2020-11-25T18:55:06Z

Would there be some way to look back at the original AST and see what #[cfg] were applied to a specific node if they get removed? Or could rustdoc run some pass before #[cfg] expansion to save this off into a side-table?

Perhaps the best way to recover this functionality would be to expand #[cfg(TRUE_PREDICATE)] ITEM into #[doc(cfg(TRUE_PREDICATE))] ITEM rather than to just ITEM in rustdoc mode.
(The key property is that the produced attribute should be inert, unlike cfg itself.)

Feel free to experiment with the impact of this change on real life code, but I'd like to block actually merging this for ~1.5 months until I get to implementing the cfg changes.

This is only active when the doc_cfg feature is active.

Changing behavior depending on feature gate (rather than just producing an error) is not a good practice, this means stabilization will be a (potentially breaking) change in behavior.

jyn514 · 2020-12-03T13:47:34Z

Changing behavior depending on feature gate (rather than just producing an error) is not a good practice, this means stabilization will be a (potentially breaking) change in behavior.

How would you suggest to do this instead? Unconditionally adding doc(cfg) will give an error that the feature gate isn't active, even projects just using cfg (which is stable).

bors · 2020-12-31T15:08:44Z

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

JohnCSimon · 2021-01-19T05:21:47Z

@rustbot modify labels: -S-waiting-on-review +S-waiting-on-author

jyn514 · 2021-01-19T05:46:18Z

@JohnCSimon as far as I know this is still waiting on response to #79341 (comment).

petrochenkov · 2021-01-20T22:02:45Z

I planned to work on cfg changes during holidays, but #79078 didn't made it in time, so cfg changes are going to be deferred to uncertain future, and I don't want to block this PR on them anymore.
It is always possible to make cfg behavior depending on whether we are running rustdoc or not, if it becomes really necessary.

If making the feature gate non-behavior-changing is hard, then it can be made behavior changing.
Still mind that stabilization will change behavior in this case.

r? @jyn514

jyn514

This looks good to me, but someone from T-libs may want to take a look at the rendered docs.

cfg changes are going to be deferred to uncertain future, and I don't want to block this PR on them anymore.

Thank you ❤️ If it makes you feel better, I think the doc(cfg) desugaring you mentioned should be possible even with the feature gate as long as there's a way to tell whether the attribute was injected by the compiler or not.

For tokio 0.3.4 this adds a bunch of Unix cfgs to the docs. There are a couple of cfg(not(loom)) that need suppressing, and some kind of bug to do with the cfg displayed for tokio::{main, test} that I need to look into.

Did you get a chance to look at the bug?

For syn 1.0.50 this exposes quite a few more cfgs that seem correct, it probably needs looking at by a syn dev to see if they really should be exposed. There's also a couple WebAssembly cfgs that need suppressing.

I'll start a try build in just a second so people can test this locally.

TODO: Update doc(cfg) docs, Add doc(cfg_hide) docs

Please add these when you get a chance. This also needs a rebase.

compiler/rustc_feature/src/active.rs

library/alloc/src/lib.rs

jyn514 · 2021-01-20T22:12:05Z

library/core/src/lib.rs

+        target_pointer_width = "16",
+        target_pointer_width = "32",
+        target_pointer_width = "64",
+        target_has_atomic = "8",
+        target_has_atomic = "16",
+        target_has_atomic = "32",
+        target_has_atomic = "64",
+        target_has_atomic = "ptr",
+        target_has_atomic_equal_alignment = "8",
+        target_has_atomic_equal_alignment = "16",
+        target_has_atomic_equal_alignment = "32",
+        target_has_atomic_equal_alignment = "64",
+        target_has_atomic_equal_alignment = "ptr",
+        target_has_atomic_load_store = "8",
+        target_has_atomic_load_store = "16",
+        target_has_atomic_load_store = "32",
+        target_has_atomic_load_store = "64",
+        target_has_atomic_load_store = "ptr",


Why hide these?

These, along with target_has_atomic_ptr, are unstable cfg. While I think it would be really nice to have this all documented on the items, I don't think the doc(cfg) presentation of them is good enough. I'll attach a screenshot of what it looks like with them unhidden.

I also think it might make sense to enhance doc(cfg_hide) to support specifying just the key of key-value cfg expressions so that these aren't duplicated for each size.

jyn514 · 2021-01-20T22:13:28Z

src/librustdoc/clean/mod.rs

@@ -272,7 +272,8 @@ impl Clean<Item> for doctree::Module<'_> {

 impl Clean<Attributes> for [ast::Attribute] {
    fn clean(&self, cx: &DocContext<'_>) -> Attributes {
-        Attributes::from_ast(cx.sess().diagnostic(), self, None)
+        let doc_cfg_active = cx.tcx.features().doc_cfg;
+        Attributes::from_ast(cx.sess().diagnostic(), self, None, doc_cfg_active, &cx.hidden_cfg)


Why put this on Attributes instead of calling tcx.features() on demand?

I found why - you use it directly in from_ast, not after Attributes is constructed. It's either this or pass a tcx; this seems fine.

jyn514 · 2021-01-20T22:16:20Z

src/librustdoc/clean/types.rs

+            fn single(self) -> Option<Self::Item> {
+                let mut iter = self.into_iter();
+                let item = iter.next()?;
+                iter.next().is_none().then_some(())?;


I think this is a little too cute :P

Suggested change

iter.next().is_none().then_some(())?;

if iter.next().is_some() {

return None;

}

I think I'll likely scrap the whole SingleExt extension trait as the diagnostics for 0 and >1 items should be different.

jyn514 · 2021-01-20T22:30:12Z

@bors try

jhpratt · 2021-04-02T09:22:31Z

Friendly ping @Nemo157 — what's the status of this?

JohnCSimon · 2021-04-18T23:09:49Z

Ping from triage:
@Nemo157 - can you please post your status?

This is only active when the `doc_cfg` feature is active. The implicit cfg can be overridden via #[doc(cfg(...))], so e.g. to hide a #[cfg] you can use something like: ```rust #[cfg(unix)] #[doc(cfg(all()))] pub struct Unix; ``` (since `all()` is always true, it is never shown in the docs)

By adding #![doc(cfg_hide(foobar))] to the crate attributes the cfg #[cfg(foobar)] (and _only_ that _exact_ cfg) will not be implicitly treated as a doc(cfg) to render a message in the documentation.

rust-log-analyzer · 2021-04-26T15:00:50Z

The job mingw-check failed! Check out the build log: (web) (plain)

Click to see the possible cause of the failure (guessed by this bot)

configure: rust.channel         := nightly
configure: rust.debug-assertions := True
configure: llvm.assertions      := True
configure: dist.missing-tools   := True
configure: build.configure-args := ['--enable-sccache', '--disable-manage-submodu ...
configure: writing `config.toml` in current directory
configure: 
configure: run `python /checkout/x.py --help`
configure: 
---
    Finished release [optimized] target(s) in 10.63s
tidy check
tidy: Skipping binary file check, read-only filesystem
Checking which error codes lack tests...
tidy error: /checkout/src/librustdoc/html/render/print_item.rs:293: TODO is deprecated; use FIXME
* highest error code: E0781
Found 515 error codes
Found 0 error codes with no tests
Done!
Done!
* 330 features
some tidy checks failed


command did not execute successfully: "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0-tools-bin/rust-tidy" "/checkout" "/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "/checkout/obj/build" "16"


failed to run: /checkout/obj/build/bootstrap/debug/bootstrap test --stage 2 src/tools/tidy
Build completed unsuccessfully in 0:00:13

bors · 2021-04-27T23:09:57Z

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

bstrie · 2021-05-12T23:35:54Z

@Nemo157 , is this PR still being pursued?

jyn514 · 2021-05-13T04:56:50Z

@bstrie this is the last update I heard: https://discord.com/channels/442252698964721669/459149231702278154/836259493741985854

I really don't think I will get time to work on it anytime soon, so if you want to do it I can help review (in which case it might make sense to close that PR and open a new one)

bstrie · 2021-06-02T23:07:28Z

Would someone like to make a tracking issue so that this can be closed, then?

GuillaumeGomez · 2021-10-06T13:43:31Z

I took this PR, rebased it and updated the code so that it can work with current rustdoc in #89596.

…jyn514 Make cfg imply doc(cfg) This is a reopening of rust-lang#79341, rebased and modified a bit (we made a lot of refactoring in rustdoc's types so they needed to be reflected in this PR as well): * `hidden_cfg` is now in the `Cache` instead of `DocContext` because `cfg` information isn't stored anymore on `clean::Attributes` type but instead computed on-demand, so we need this information in later parts of rustdoc. * I removed the `bool_to_options` feature (which makes the code a bit simpler to read for `SingleExt` trait implementation. * I updated the version for the feature. There is only one thing I couldn't figure out: [this comment](rust-lang#79341 (comment)) > I think I'll likely scrap the whole `SingleExt` extension trait as the diagnostics for 0 and >1 items should be different. How/why should they differ? EDIT: this part has been solved, the current code was fine, just needed a little simplification. cc `@Nemo157` r? `@jyn514` Original PR description: This is only active when the `doc_cfg` feature is active. The implicit cfg can be overridden via `#[doc(cfg(...))]`, so e.g. to hide a `#[cfg]` you can use something like: ```rust #[cfg(unix)] #[doc(cfg(all()))] pub struct Unix; ``` By adding `#![doc(cfg_hide(foobar))]` to the crate attributes the cfg `#[cfg(foobar)]` (and _only_ that _exact_ cfg) will not be implicitly treated as a `doc(cfg)` to render a message in the documentation.

rust-highfive assigned ollie27 Nov 23, 2020

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

Nemo157 force-pushed the implicit-doc-cfg branch from 1ba3a96 to 178c32c Compare November 23, 2020 12:41

jyn514 added F-doc_cfg `#![feature(doc_cfg)]` T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. labels Nov 23, 2020

petrochenkov self-assigned this Nov 23, 2020

petrochenkov removed their assignment Nov 25, 2020

petrochenkov added the T-compiler Relevant to the compiler team, which will review and decide on the PR/issue. label Nov 25, 2020

petrochenkov mentioned this pull request Nov 27, 2020

Replace pretty-print/compare/retokenize hack with targeted workarounds #79472

Merged

jhpratt mentioned this pull request Dec 22, 2020

Stabilize doc_cfg feature #79263

Closed

rustbot added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jan 19, 2021

jyn514 added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jan 19, 2021

jyn514 assigned petrochenkov Jan 19, 2021

rust-highfive assigned jyn514 and unassigned petrochenkov and ollie27 Jan 20, 2021

jyn514 reviewed Jan 20, 2021

View reviewed changes

crlf0710 added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 20, 2021

GuillaumeGomez mentioned this pull request Mar 23, 2021

doc_cfg hints not shown on reexports from private modules gtk-rs/gir#1079

Open

3 tasks

petrochenkov mentioned this pull request Apr 15, 2021

Remove #[cfg] attributes during cfg-expansion #84110

Closed

JohnCSimon added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Apr 18, 2021

jyn514 force-pushed the implicit-doc-cfg branch from 8870ae1 to e6ac7aa Compare April 23, 2021 14:33

This comment has been minimized.

Sign in to view

taiki-e mentioned this pull request Apr 23, 2021

Remove uses of unstable feature(cfg_target_has_atomic) rust-lang/futures-rs#2400

Merged

This comment has been minimized.

Sign in to view

jyn514 changed the title ~~Make cfg implicitly imply doc(cfg)~~ Make cfg imply doc(cfg) Apr 26, 2021

Nemo157 and others added 5 commits April 26, 2021 10:23

Allow adding a set of cfg's to hide from being implicitly doc(cfg)'d

74d0d3f

By adding #![doc(cfg_hide(foobar))] to the crate attributes the cfg #[cfg(foobar)] (and _only_ that _exact_ cfg) will not be implicitly treated as a doc(cfg) to render a message in the documentation.

Suppress some cfg from being shown in the stdlib docs

e0c438f

Add test case for doc_cfg_hide feature gate

28500e7

Add cfg_hide to the list of known attributes

0225d97

jyn514 force-pushed the implicit-doc-cfg branch from 7458146 to 0225d97 Compare April 26, 2021 14:25

jyn514 mentioned this pull request Jun 16, 2021

RFC: fallible-allocation rust-lang/rfcs#3140

Open

JohnCSimon closed this Jun 20, 2021

GuillaumeGomez mentioned this pull request Oct 6, 2021

Make cfg imply doc(cfg) #89596

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make cfg imply doc(cfg) #79341

Make cfg imply doc(cfg) #79341

Nemo157 commented Nov 23, 2020 •

edited

Loading

rust-highfive commented Nov 23, 2020

petrochenkov commented Nov 23, 2020 •

edited

Loading

Nemo157 commented Nov 23, 2020

Nemo157 commented Nov 23, 2020

petrochenkov commented Nov 25, 2020

jyn514 commented Dec 3, 2020

bors commented Dec 31, 2020

JohnCSimon commented Jan 19, 2021

jyn514 commented Jan 19, 2021

petrochenkov commented Jan 20, 2021

jyn514 left a comment

jyn514 Jan 20, 2021

Nemo157 Jan 21, 2021

jyn514 Jan 20, 2021

jyn514 Feb 24, 2021

jyn514 Jan 20, 2021

Nemo157 Jan 21, 2021

jyn514 commented Jan 20, 2021

jhpratt commented Apr 2, 2021

JohnCSimon commented Apr 18, 2021

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rust-log-analyzer commented Apr 26, 2021

bors commented Apr 27, 2021

bstrie commented May 12, 2021

jyn514 commented May 13, 2021

bstrie commented Jun 2, 2021 •

edited

Loading

GuillaumeGomez commented Oct 6, 2021

-                iter.next().is_none().then_some(())?;
+                if iter.next().is_some() {
+                    return None;
+                }

Make cfg imply doc(cfg) #79341

Make cfg imply doc(cfg) #79341

Conversation

Nemo157 commented Nov 23, 2020 • edited Loading

rust-highfive commented Nov 23, 2020

petrochenkov commented Nov 23, 2020 • edited Loading

Nemo157 commented Nov 23, 2020

Nemo157 commented Nov 23, 2020

petrochenkov commented Nov 25, 2020

jyn514 commented Dec 3, 2020

bors commented Dec 31, 2020

JohnCSimon commented Jan 19, 2021

jyn514 commented Jan 19, 2021

petrochenkov commented Jan 20, 2021

jyn514 left a comment

Choose a reason for hiding this comment

jyn514 Jan 20, 2021

Choose a reason for hiding this comment

Nemo157 Jan 21, 2021

Choose a reason for hiding this comment

jyn514 Jan 20, 2021

Choose a reason for hiding this comment

jyn514 Feb 24, 2021

Choose a reason for hiding this comment

jyn514 Jan 20, 2021

Choose a reason for hiding this comment

Nemo157 Jan 21, 2021

Choose a reason for hiding this comment

jyn514 commented Jan 20, 2021

jhpratt commented Apr 2, 2021

JohnCSimon commented Apr 18, 2021

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rust-log-analyzer commented Apr 26, 2021

bors commented Apr 27, 2021

bstrie commented May 12, 2021

jyn514 commented May 13, 2021

bstrie commented Jun 2, 2021 • edited Loading

GuillaumeGomez commented Oct 6, 2021

Nemo157 commented Nov 23, 2020 •

edited

Loading

petrochenkov commented Nov 23, 2020 •

edited

Loading

bstrie commented Jun 2, 2021 •

edited

Loading