Skip to content

rustdoc: Reify emission types#155679

Open
fmease wants to merge 1 commit intorust-lang:mainfrom
fmease:rustdoc-reify-emission-types
Open

rustdoc: Reify emission types#155679
fmease wants to merge 1 commit intorust-lang:mainfrom
fmease:rustdoc-reify-emission-types

Conversation

@fmease
Copy link
Copy Markdown
Member

@fmease fmease commented Apr 23, 2026

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).

@rustbot rustbot added A-rustdoc-json Area: Rustdoc JSON backend S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output. labels Apr 23, 2026
Comment thread src/librustdoc/config.rs
dcx.fatal(format!("unrecognized emission type: {typ}"))
};

match typ {
Copy link
Copy Markdown
Member Author

@fmease fmease Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/librustdoc/config.rs
// 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() {
Copy link
Copy Markdown
Member Author

@fmease fmease Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread src/librustdoc/config.rs
Comment on lines +523 to +525
if let OutputFormat::Doctest = output_format {
dcx.fatal("the `--emit` flag is not supported with `--output-format=doctest`");
}
Copy link
Copy Markdown
Member Author

@fmease fmease Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

View changes since the review

@fmease fmease marked this pull request as ready for review April 23, 2026 09:27
@rustbot 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
Comment thread src/librustdoc/config.rs
"the `--emit={emit_flag}` flag is not supported with `--output-format=json`",
));
let mut emit = FxIndexMap::default();
for list in matches.opt_strs("emit") {
Copy link
Copy Markdown
Member Author

@fmease fmease Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-rustdoc-json Area: Rustdoc JSON backend S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. T-rustdoc-frontend Relevant to the rustdoc-frontend team, which will review and decide on the web UI/UX output.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants