Description
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.
NOTE: As of September 2020 this is no longer true, see #76578 for --output-format json.
--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.