rustdoc: Rename --show-coverage to --output-format coverage (and coverage-json)

[jyn514]

Right now, --output-format is greatly overloaded (as seen by #82497). --output-format json is unstable, except when you use it with --show-coverage. Also, --show-coverage is not great at conveying that it stops documentation from being generated at all.

I suggest that we rename --show-coverage to --output-format coverage and --show-coverage --output-format json to --output-format coverage-json, deprecate the old uses for a few releases, and then remove them.

[camelid]

Hmm, --output-format coverage[-json] seems confusing to me. --output-format implies to me that my docs will be outputted to a different format than the default, whereas --output-format coverage is telling rustdoc to output different data. IMO, this seems like it would overload --output-format even more.

My understanding from the discussion that this issue came from is that the user thought --show-coverage was generating HTML docs because it was slow. But, AIUI, generating HTML docs is actually not the slow part of rustdoc; it's the data collection phase (looking at you, get_blanket_impls!) that's slow, which --show-coverage has to run anyway. Do we know of cases where the --show-coverage CLI behavior was confusing to people, outside of it being slow, which we can only fix by making rustdoc more performant?

[jyn514]

Being slow doesn't have anything to do with this. The reason I think we should rename it is because --show-coverage to me sounds like it shows the coverage in addition to generating the docs. If it's under --output-format then it's clear that it replaces the docs instead.

[camelid]

Being slow doesn't have anything to do with this. The reason I think we should rename it is because --show-coverage to me sounds like it shows the coverage in addition to generating the docs. If it's under --output-format then it's clear that it replaces the docs instead.

Yeah, I see how that could be confusing. But I find --output-format coverage somewhat confusing as well :/

[Nemo157]

Something I'm sure I saw someone else mention ages ago, and which I really like, is to use --print coverage and --print coverage-json for consistency with rustc's --print options (though it doesn't have any that has both a pair of "user-facing" and machine-readable).

[camelid]

Something I'm sure I saw someone else mention ages ago, and which I really like, is to use --print coverage and --print coverage-json for consistency with rustc's --print options (though it doesn't have any that has both a pair of "user-facing" and machine-readable).

I like that idea, but rustc --print still compiles your code, while rustdoc's hypothetical --print would not generate documentation. My understanding is this issue is open because people thought --show-coverage would also generate docs.

That said, I do like the idea of --print coverage :)

[jyn514]

@camelid rustc --print does not compile your code.

> rustc --print crate-name external-doc.rs 
external_doc
> file external_doc
external_doc: cannot open `external_doc' (No such file or directory)

[camelid]

It does for some uses of --print, just not --print crate-name:

~/foo
❯ rustc --print native-static-libs foo.rs

~/foo
❯ file foo
foo: Mach-O 64-bit executable x86_64

But it's good to know that there's some precedent for us having --print not generate docs.