rustdoc: Reify emission types by fmease · Pull Request #155679 · rust-lang/rust

fmease · 2026-04-23T09:16:29Z

Instead of maintaining the hidden assumption or invariant that opts.emit.is_empty() actually means "emit default artifacts" (i.e., [HtmlStaticFiles, HtmlNonStaticFiles] under output format html; "[???]" under output format json), actually reify the list of emission types so the rest of the code doesn't need to keep this in mind.

I'm not sure if you like this. It's a tinge overengineered, maybe, but it's more robust I claim.

This PR also rejects --emit when --output-format doctest -Zunstable-options is passed since the latter doesn't honor emission types at all (yet).

fmease · 2026-04-23T09:17:44Z

+                    dcx.fatal(format!("unrecognized emission type: {typ}"))
+                };
+
+                match typ {


A match (output_format, typ) { … } / match (typ, output_format) { … } looked less legible in my eyes esp. due to rustfmt's decisions.

View changes since the review

fmease · 2026-04-23T09:24:40Z

+        // If `--emit` is absent we'll register default emission types depending on the requested
+        // output format. We can safely use `is_empty` for this since `--emit=` ("truly empty")
+        // will have already been rejected above.
+        if emit.is_empty() {


Alternatively, I could change the earlier emit from FxIndexMap to Option<FxIndexMap> to avoid conflating Some([]) with None which would be more robust and future-proof but slightly more annoying to construct.

View changes since the review

fmease · 2026-04-23T09:27:44Z

+            if let OutputFormat::Doctest = output_format {
+                dcx.fatal("the `--emit` flag is not supported with `--output-format=doctest`");
+            }


If you do like this PR I'll of course add a test for this.

View changes since the review

fmease · 2026-04-23T09:45:12Z

-                    "the `--emit={emit_flag}` flag is not supported with `--output-format=json`",
-                ));
+        let mut emit = FxIndexMap::default();
+        for list in matches.opt_strs("emit") {


Unrelated and already brought up in the stabilization PR, I'm more and more leaning towards fully ditching -w, --output-format in favor of --emit because the current setup makes my head spin (the loose proposal to repurpose--output and the one to add --print doesn't help ^^).

--emit=json-files and --emit=doctests could be wonderful. Of course, we probably want to make some emission types mutually exclusive then … which might not be in line with its "spirit" but oh well

View changes since the review

Of course, we probably want to make some emission types mutually exclusive then

This doesn't seem obvious to me. I know there are several barriers that prevent rustdoc from emitting json and html at the same time:

The output format changes the resulting Clean AST, because HTML is inlined and JSON isn't.

Constructing clean::Crate mutates DocContext, so we can't just construct Clean twice.

You'll want to be able to specify a different output location for the JSON than for the HTML.

Some cleaning-related processes produce warnings, and we don't want duplicates.

If either of those first two barriers were fixed, wouldn't --emit=html-static-files,html-non-static-files,json-file=./target/doc-json/CRATENAME.json make sense?

I guess it would indeed make sense if it's feasible to fix these issues 👍.

Let me change my statement to the following then: "If we were to introduce --emit=json-files and ditch -wjson, we would want to make the html-* emission types incompatible with json-files for the time being until we have figured out how to make them compatible implementation-wise".

In any case, this topic isn't strictly related to this PR which is a mere internal refactoring plus a fix for an unstable feature (-wdoctest) and shouldn't block it in the slightest :)

fmease · 2026-05-07T11:04:51Z

What do you think of this PR itself? Irrespective of potential future plans for --emit that is?

notriddle · 2026-05-07T12:58:04Z

Other than the lack of tests, this seems okay. If nobody else has a problem, and if tests are added, I’d be happy to merge this.

rustbot · 2026-05-09T22:44:37Z

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.

fmease · 2026-05-09T22:44:58Z

Test added.

notriddle · 2026-05-10T05:51:16Z

@bors r+

rust-bors · 2026-05-10T05:51:19Z

📌 Commit ef282ff has been approved by notriddle

It is now in the queue for this repository.

…s, r=notriddle rustdoc: Reify emission types Implements rust-lang#155374 (comment): Instead of maintaining the hidden assumption or invariant that `opts.emit.is_empty()` actually means "emit default artifacts" (i.e., `[HtmlStaticFiles, HtmlNonStaticFiles]` under output format `html`; "`[???]`" under output format `json`), actually *reify* the list of emission types so the rest of the code doesn't need to keep this in mind. I'm not sure if you like this. It's a tinge overengineered, maybe, but it's more robust I claim. This PR also rejects `--emit` when `--output-format doctest -Zunstable-options` is passed since the latter doesn't honor emission types at all (yet).

Rollup of 6 pull requests Successful merges: - #153975 (remove forever-deprecated and hidden `f64` methods) - #155679 (rustdoc: Reify emission types) - #155982 (Fix closure HIR span context mismatch) - #156323 (Handle --print=backend-has-mnemonic in cg_clif) - #156129 (compiletest: Migrate from `PassMode`/`FailMode` to `PassFailMode`) - #156365 (stream_send_recv_stress tests: wait for threads to finish)

rust-bors · 2026-05-10T14:06:07Z

⌛ Testing commit ef282ff with merge 9788718...

Workflow: https://github.com/rust-lang/rust/actions/runs/25630769060

rustdoc: Reify emission types Implements #155374 (comment): Instead of maintaining the hidden assumption or invariant that `opts.emit.is_empty()` actually means "emit default artifacts" (i.e., `[HtmlStaticFiles, HtmlNonStaticFiles]` under output format `html`; "`[???]`" under output format `json`), actually *reify* the list of emission types so the rest of the code doesn't need to keep this in mind. I'm not sure if you like this. It's a tinge overengineered, maybe, but it's more robust I claim. This PR also rejects `--emit` when `--output-format doctest -Zunstable-options` is passed since the latter doesn't honor emission types at all (yet).

…s, r=notriddle rustdoc: Reify emission types Implements rust-lang#155374 (comment): Instead of maintaining the hidden assumption or invariant that `opts.emit.is_empty()` actually means "emit default artifacts" (i.e., `[HtmlStaticFiles, HtmlNonStaticFiles]` under output format `html`; "`[???]`" under output format `json`), actually *reify* the list of emission types so the rest of the code doesn't need to keep this in mind. I'm not sure if you like this. It's a tinge overengineered, maybe, but it's more robust I claim. This PR also rejects `--emit` when `--output-format doctest -Zunstable-options` is passed since the latter doesn't honor emission types at all (yet).

JonathanBrouwer · 2026-05-10T14:13:34Z

@bors yield
Yielding to enclosing rollup

rust-bors · 2026-05-10T14:13:37Z

Auto build was cancelled. Cancelled workflows:

https://github.com/rust-lang/rust/actions/runs/25630769060

The next pull request likely to be tested is #156397.

…uwer Rollup of 6 pull requests Successful merges: - #155679 (rustdoc: Reify emission types) - #155982 (Fix closure HIR span context mismatch) - #156323 (Handle --print=backend-has-mnemonic in cg_clif) - #156129 (compiletest: Migrate from `PassMode`/`FailMode` to `PassFailMode`) - #156365 (stream_send_recv_stress tests: wait for threads to finish) - #156368 (Fix invalid unreachable in is_known_valid_scrutinee for Reborrow)

rust-bors · 2026-05-10T15:20:47Z

⌛ Testing commit ef282ff with merge 8f1bc40...

Workflow: https://github.com/rust-lang/rust/actions/runs/25632375858

rustdoc: Reify emission types Implements #155374 (comment): Instead of maintaining the hidden assumption or invariant that `opts.emit.is_empty()` actually means "emit default artifacts" (i.e., `[HtmlStaticFiles, HtmlNonStaticFiles]` under output format `html`; "`[???]`" under output format `json`), actually *reify* the list of emission types so the rest of the code doesn't need to keep this in mind. I'm not sure if you like this. It's a tinge overengineered, maybe, but it's more robust I claim. This PR also rejects `--emit` when `--output-format doctest -Zunstable-options` is passed since the latter doesn't honor emission types at all (yet).

JonathanBrouwer · 2026-05-10T15:30:43Z

@bors yield
Yielding to enclosing rollup

rust-bors · 2026-05-10T15:30:46Z

Auto build was cancelled. Cancelled workflows:

https://github.com/rust-lang/rust/actions/runs/25632375858

The next pull request likely to be tested is #156397.

…uwer Rollup of 6 pull requests Successful merges: - #155679 (rustdoc: Reify emission types) - #155982 (Fix closure HIR span context mismatch) - #156323 (Handle --print=backend-has-mnemonic in cg_clif) - #156129 (compiletest: Migrate from `PassMode`/`FailMode` to `PassFailMode`) - #156365 (stream_send_recv_stress tests: wait for threads to finish) - #156368 (Fix invalid unreachable in is_known_valid_scrutinee for Reborrow)

…uwer Rollup of 10 pull requests Successful merges: - #156394 (miri subtree update) - #154972 (Implement `core::arch::return_address` and tests) - #155679 (rustdoc: Reify emission types) - #155982 (Fix closure HIR span context mismatch) - #156323 (Handle --print=backend-has-mnemonic in cg_clif) - #156387 (std fs tests: avoid matching on OS-provided error string) - #156129 (compiletest: Migrate from `PassMode`/`FailMode` to `PassFailMode`) - #156192 (core: Replace `ptr::slice_from_raw_parts` with `slice::from_raw_parts`) - #156365 (stream_send_recv_stress tests: wait for threads to finish) - #156368 (Fix invalid unreachable in is_known_valid_scrutinee for Reborrow)

…uwer Rollup of 10 pull requests Successful merges: - rust-lang/rust#156394 (miri subtree update) - rust-lang/rust#154972 (Implement `core::arch::return_address` and tests) - rust-lang/rust#155679 (rustdoc: Reify emission types) - rust-lang/rust#155982 (Fix closure HIR span context mismatch) - rust-lang/rust#156323 (Handle --print=backend-has-mnemonic in cg_clif) - rust-lang/rust#156387 (std fs tests: avoid matching on OS-provided error string) - rust-lang/rust#156129 (compiletest: Migrate from `PassMode`/`FailMode` to `PassFailMode`) - rust-lang/rust#156192 (core: Replace `ptr::slice_from_raw_parts` with `slice::from_raw_parts`) - rust-lang/rust#156365 (stream_send_recv_stress tests: wait for threads to finish) - rust-lang/rust#156368 (Fix invalid unreachable in is_known_valid_scrutinee for Reborrow)

fmease assigned notriddle Apr 23, 2026

fmease commented Apr 23, 2026

View reviewed changes

fmease marked this pull request as ready for review April 23, 2026 09:27

rustbot 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 Apr 23, 2026

fmease commented Apr 23, 2026

View reviewed changes

fmease force-pushed the rustdoc-reify-emission-types branch from b5f0ae7 to 4d8ebc9 Compare May 9, 2026 22:44

rustdoc: Reify emission types

ef282ff

fmease force-pushed the rustdoc-reify-emission-types branch from 4d8ebc9 to ef282ff Compare May 9, 2026 22:54

rust-bors Bot added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels May 10, 2026

matthiaskrgr mentioned this pull request May 10, 2026

Rollup of 6 pull requests #156386

Closed

JonathanBrouwer mentioned this pull request May 10, 2026

Rollup of 6 pull requests #156397

Closed

JonathanBrouwer mentioned this pull request May 10, 2026

Rollup of 10 pull requests #156405

Merged

rust-bors Bot merged commit 63e70d5 into rust-lang:main May 10, 2026
11 of 12 checks passed

rustbot added this to the 1.97.0 milestone May 10, 2026

fmease deleted the rustdoc-reify-emission-types branch May 10, 2026 23:14

Uh oh!

Conversation

fmease commented Apr 23, 2026

Uh oh!

fmease Apr 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Apr 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Apr 23, 2026 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

notriddle Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

fmease May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

fmease commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

notriddle commented May 7, 2026

Uh oh!

rustbot commented May 9, 2026

Uh oh!

fmease commented May 9, 2026

Uh oh!

notriddle commented May 10, 2026

Uh oh!

rust-bors Bot commented May 10, 2026

Uh oh!

rust-bors Bot commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JonathanBrouwer commented May 10, 2026

Uh oh!

rust-bors Bot commented May 10, 2026

Uh oh!

rust-bors Bot commented May 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JonathanBrouwer commented May 10, 2026

Uh oh!

rust-bors Bot commented May 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

fmease Apr 23, 2026 •

edited by rustbot

Loading

fmease Apr 23, 2026 •

edited by rustbot

Loading

fmease Apr 23, 2026 •

edited by rustbot

Loading

fmease Apr 23, 2026 •

edited

Loading

fmease May 7, 2026 •

edited

Loading

fmease commented May 7, 2026 •

edited

Loading

rust-bors Bot commented May 10, 2026 •

edited

Loading

rust-bors Bot commented May 10, 2026 •

edited

Loading