-
-
Notifications
You must be signed in to change notification settings - Fork 14.8k
Tracking issue for rustdoc deprecations/cleanup #44136
Copy link
Copy link
Closed
Labels
C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCCategory: An issue tracking the progress of sth. like the implementation of an RFCT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.Relevant to the dev-tools subteam, which will review and decide on the PR/issue.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.Relevant to the rustdoc team, which will review and decide on the PR/issue.
Description
Metadata
Metadata
Assignees
Labels
C-tracking-issueCategory: An issue tracking the progress of sth. like the implementation of an RFCCategory: An issue tracking the progress of sth. like the implementation of an RFCT-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.Relevant to the dev-tools subteam, which will review and decide on the PR/issue.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.Relevant to the rustdoc team, which will review and decide on the PR/issue.
Type
Fields
Give feedbackNo fields configured for issues without a type.
In a recent @rust-lang/dev-tools meeting, we chatted about some compatibility issues with
rustdoc. A lot ofrustdocwas 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/--passesMore 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-formatThese 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/--pluginsRustdoc 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/--passesThese 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.