Rust: Tracking issue for rustdoc deprecations/cleanup

[steveklabnik]

In a recent @rust-lang/dev-tools meeting, we chatted about some compatibility issues with rustdoc. A lot of rustdoc was never really strongly thought-through, or there were grand plans that never really materialized.

As such, we want to deprecate and then remove some things that we don't believe anyone is using, and provide better support for some things people are doing, but in a hacky way.

Summary of plans, to be checked off as they're done:

• [ ] --input-format/--output-format
• [ ] --plugin-path/--plugins
• [ ] --no-defaults/--passes

More details below.

In addition, when it's closer to ship the new rustdoc, the various HTML and CSS flags will probably be replaced by a real templating system, and so we'll need to introduce some messaging there. That's not part of this ticket, however.

--input-format/--output-format

These flags are completely ignored today. Originally there were big plans, but not anymore.

These should be deprecated and hidden from the docs.

--plugin-path/--plugins

Rustdoc supports plugins, who knew? The approach here is plagued with problems; dynamic library loading, exposing internal rustdoc types, no real guarantees. We're not aware of anyone even using this functionality.

These should be deprecated, and eventually, the functionality should be removed.

--no-defaults/--passes

These flags have one known use today: to document private items by removing all passes, and then sending in the passes that don't strip private items.

We should deprecate these flags, and eventually remove the functionality, however, this should not be done without adding a new flag, to be named, to just actually generate private docs.

[BartMassey]

I occasionally document a Rust binary crate with this:

cargo rustdoc --open -- --no-defaults \
  --passes collapse-docs   \
  --passes unindent-comments \
  --passes strip-priv-imports

These days I get a warning about deprecated flags per this issue.

I can use the incantation below instead, but that isn't quite the same: there's a "Re-exports" section tacked on the front page that arguably doesn't make much sense for a binary crate.

cargo rustdoc --open -- --document-private-items

[jonas-schievink]

Yeah this really should imply --passes strip-priv-imports. Private imports are just visual noise even when I'm interested in the guts of the crate I work on.

[QuietMisdreavus]

strip-priv-imports was added to the default private passes in https://github.com/rust-lang/rust/pull/52751.

[jonas-schievink]

@QuietMisdreavus Great, thanks!

[araspik]

So there is _no way_ to get JSON output or similar for documentation purposes? I wanted to hack together an info file creator (shell script or something) but it seems that -w json no longer works.

[QuietMisdreavus]

Correct, HTML is the only available output format for rustdoc right now. We are planning on re-introducing JSON output this year, but work on that has not yet started.

[GuillaumeGomez]

I'll *soon* though.