bootstrap: Include feature-gated items in bootstrap tool docs

[Zalathar]

View all comments

I noticed that the nightly-rustc docs for build_helper don't include the metrics module, because it's gated behind the non-default feature flag feature = "metrics".

This PR fixes that by using --all-features to document all features, and enabling rustdoc's #![feature(doc_cfg)] (via -Zcrate-attr) so that rustdoc will indicate which items require feature flags.

The first two commits are a general cleanup of tool_doc! to pull almost all of its non-trivial code out of the macro and into regular functions.

[rustbot]

r? @Mark-Simulacrum

rustbot has assigned @Mark-Simulacrum.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: bootstrap
• bootstrap expanded to 6 candidates
• Random selection from Mark-Simulacrum, clubby789

[Zalathar]

As a follow-up we could also enable this for compiler crates, since a few of them have feature flags to enable nightly-only features when they aren't being used by rust-analyzer.

[Zalathar]

I would also like to note that this would have been much more annoying without -Zcrate-attr.

[Zalathar]

I really want to blanket allow clippy::too_many_arguments and clippy::type_complexity across all of bootstrap, but I won't do that in this PR.

[Kobzol]

r? kobzol

Note that this will conflict a lot with #161716. In general I'm happy to see most of the code move out of a macro.

[Kobzol]

Aside: do you find the build_helper/bootstrap docs being present in the nightly rustc docs useful?

[Zalathar]

Aside: do you find the build_helper/bootstrap docs being present in the nightly rustc docs useful?

I use the nightly-rustc docs intermittently, but when I do reach for them it's nice to have everything there in one place, especially when I'm not at a computer and can't easily search the source.

[Zalathar]

Note that this will conflict a lot with #161716. In general I'm happy to see most of the code move out of a macro.

If conflicts are a concern, I can potentially cut this PR down to just the main fix (within the macro), and defer the macro-extraction to follow-up work.

(I had to do the extraction to work on the fix, but now that I have the fix it should be easy to backport to main.)

[Kobzol]

I'd perhaps either do that, or wait for the other PR to get merged, yeah.

[Zalathar]

@rustbot blocked (on #161716 to avoid conflicts)

[Zalathar]

@rustbot ready

[Kobzol]

Looks good, thanks! Feel free to r=me once PR CI is green.

[Zalathar]

PR CI is green.

@bors r=Kobzol

[rust-bors]

📌 Commit 8f1843d has been approved by Kobzol

It is now in the queue for this repository.

[rust-bors]

💔 Test for 3ec43f9 failed: CI. Failed job:

• try - dist-x86_64-linux-alt (web logs, enhanced plaintext logs)

[rustbot]

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

[Zalathar]

Since CI has been weird today, let's run the try job again, after a fresh rebase.

@bors try jobs=dist-x86_64-linux-alt

[rust-bors]

💔 Test for c4394bd failed: CI. Failed job:

• try - dist-x86_64-linux-alt (web logs, enhanced plaintext logs)

[Zalathar]

I can reproduce the failure locally, so it's a real failure.

It seems to be triggered by the added cargo.arg("--all-features"). So perhaps there's some non-default rustfmt feature that is doing weird things.

[Zalathar]

In order to fix the rustfmt doc failures, I added a flag to selectively disable --all-features for a particular tool.

As a prerequisite to that, I also did a general cleanup of the syntax used by tool_doc!, because the current syntax is confusingly inconsistent.

@bors try jobs=dist-x86_64-linux-alt
@rustbot ready

[rust-bors]

💔 Test for f1cd7dd failed: CI. Failed job:

• try - dist-x86_64-linux-alt (web logs, enhanced plaintext logs)

[Zalathar]

Looks like Miri is also having trouble. Let's keep excluding tools until we find a configuration that works.

@bors try jobs=dist-x86_64-linux-alt

[rust-bors]

☀️ Try build successful (CI)
Build commit: 61661af (61661af10956e3a8709378e2fe4c88a1a1568c0d)
Base parent: 0ed41eb (0ed41eb4142dda2df61eb1145a312c1a9d62eb56)