Tracking issue for rustdoc deprecations/cleanup #44136

steveklabnik · 2017-08-28T20:48:38Z

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.

The text was updated successfully, but these errors were encountered:

Part of rust-lang#44136

…r=Manishearth Deprecate several flags in rustdoc Part of rust-lang#44136 cc @rust-lang/dev-tools @rust-lang/docs This is a very basic PR to start deprecating some flags; `rustdoc` doesn't really have fancy output options like `rustc` does, so I went with `eprintln!`. Happy to change it if people feel that's not appropriate. Also, I have no idea if we can or should write tests here, so I didn't try. If someone feels strongly about it, then let's do it, but given that the only outcome here is a side effect...

Part of rust-lang#44136 Upgrades cargo due to rust-lang/cargo#4451

…r=QuietMisdreavus Deprecate several flags in rustdoc Part of rust-lang#44136 cc @rust-lang/dev-tools @rust-lang/docs This is a very basic PR to start deprecating some flags; `rustdoc` doesn't really have fancy output options like `rustc` does, so I went with `eprintln!`. Happy to change it if people feel that's not appropriate. Also, I have no idea if we can or should write tests here, so I didn't try. If someone feels strongly about it, then let's do it, but given that the only outcome here is a side effect...

…=GuillaumeGomez rustdoc: deprecate `#![doc(passes, plugins, no_default_passes)]` Closes rust-lang#48164 Blocked on rust-lang#50541 - this includes those changes, which were necessary to create the UI test cc rust-lang#44136 Turns out, there were special attributes to mess with rustdoc passes and plugins! Who knew! Since we deprecated the CLI flags for this functionality, it makes sense that we do the same for the attributes. This PR also introduces a `#![doc(document_private_items)]` attribute, to match the `--document-private-items` flag introduced in rust-lang#44138 when the passes/plugins flags were deprecated. I haven't done a search to see whether these attributes are being used at all, but if the flags were any indication, i don't expect to see any users of these.

BartMassey · 2018-06-03T17:48:37Z

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 · 2018-08-22T23:56:57Z

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 · 2018-08-23T21:41:03Z

strip-priv-imports was added to the default private passes in #52751.

jonas-schievink · 2018-08-23T21:44:19Z

@QuietMisdreavus Great, thanks!

araspik · 2019-02-25T19:20:07Z

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 · 2019-02-25T19:22:06Z

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 · 2019-02-26T11:34:48Z

I'll *soon* though.

- Don't treat it as deprecated on stable and beta channels. Before, it would give confusing and incorrect output: ``` warning: the 'output-format' flag is considered deprecated | = warning: see issue rust-lang#44136 <rust-lang#44136> for more information error: json output format isn't supported for doc generation ``` Both of those are wrong: output-format isn't deprecated, and json output is supported. - Require -Z unstable-options for `--output-format json` Previously, it was allowed by default on nightly, which made it hard to realize the flag wouldn't be accepted on beta or stable. Note that this still allows `--output-format html`, which has been stable since 1.0. - Remove unnecessary double-checking of the feature gate when parsing the output format - Add custom run-make test since compiletest passes -Zunstable-options by default

Fix handling of `--output-format json` flag - Don't treat it as deprecated on stable and beta channels. Before, it would give confusing and incorrect output: ``` warning: the 'output-format' flag is considered deprecated | = warning: see issue rust-lang#44136 <rust-lang#44136> for more information error: json output format isn't supported for doc generation ``` Both of those are wrong: output-format isn't deprecated, and json output is supported. - Require -Z unstable-options for `--output-format json` Previously, it was allowed by default on nightly, which made it hard to realize the flag wouldn't be accepted on beta or stable. To get the test working I had to remove `-Z unstable-options`, which x.py passed to compiletest unconditionally. It was first added in rust-lang@8c2ec68 so `-Z miri` would be allowed. -Z miri is no longer passed unconditionally, so hopefully removing it won't break anything. r? `@aDotInTheVoid` cc `@HeroicKatora` `@CraftSpider` Thanks to `@memoryruins` for pointing it out on Discord! cc `@Mark-Simulacrum` for the change to compiletest.

Fix handling of `--output-format json` flag - Don't treat it as deprecated on stable and beta channels. Before, it would give confusing and incorrect output: ``` warning: the 'output-format' flag is considered deprecated | = warning: see issue rust-lang#44136 <rust-lang#44136> for more information error: json output format isn't supported for doc generation ``` Both of those are wrong: output-format isn't deprecated, and json output is supported. - Require -Z unstable-options for `--output-format json` Previously, it was allowed by default on nightly, which made it hard to realize the flag wouldn't be accepted on beta or stable. To get the test working I had to remove `-Z unstable-options`, which x.py passed to compiletest unconditionally. It was first added in rust-lang@8c2ec68 so `-Z miri` would be allowed. -Z miri is no longer passed unconditionally, so hopefully removing it won't break anything. r? ``@aDotInTheVoid`` cc ``@HeroicKatora`` ``@CraftSpider`` Thanks to ``@memoryruins`` for pointing it out on Discord! cc ``@Mark-Simulacrum`` for the change to compiletest.

Fix handling of `--output-format json` flag - Don't treat it as deprecated on stable and beta channels. Before, it would give confusing and incorrect output: ``` warning: the 'output-format' flag is considered deprecated | = warning: see issue rust-lang#44136 <rust-lang#44136> for more information error: json output format isn't supported for doc generation ``` Both of those are wrong: output-format isn't deprecated, and json output is supported. - Require -Z unstable-options for `--output-format json` Previously, it was allowed by default on nightly, which made it hard to realize the flag wouldn't be accepted on beta or stable. To get the test working I had to remove `-Z unstable-options`, which x.py passed to compiletest unconditionally. It was first added in rust-lang@8c2ec68 so `-Z miri` would be allowed. -Z miri is no longer passed unconditionally, so hopefully removing it won't break anything. r? ```@aDotInTheVoid``` cc ```@HeroicKatora``` ```@CraftSpider``` Thanks to ```@memoryruins``` for pointing it out on Discord! cc ```@Mark-Simulacrum``` for the change to compiletest.

steveklabnik added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. C-tracking-issue Category: A tracking issue for an RFC or an unstable feature. T-dev-tools Relevant to the dev-tools subteam, which will review and decide on the PR/issue. labels Aug 28, 2017

steveklabnik mentioned this issue Aug 28, 2017

Deprecate several flags in rustdoc #44138

Merged

steveklabnik added a commit to steveklabnik/rust that referenced this issue Aug 28, 2017

Deprecate several flags in rustdoc

4cd5314

Part of rust-lang#44136

steveklabnik added a commit to steveklabnik/rust that referenced this issue Oct 17, 2017

Deprecate several flags in rustdoc

4adf6ae

Part of rust-lang#44136 Upgrades cargo due to rust-lang/cargo#4451

alexcrichton closed this as completed in aad8787 Oct 18, 2017

QuietMisdreavus mentioned this issue May 11, 2018

rustdoc: deprecate #![doc(passes, plugins, no_default_passes)] #50669

Merged

BartMassey mentioned this issue Jun 3, 2018

cargo doc doesn't generate documentation for binary crate rust-lang/cargo#1865

Closed

QuietMisdreavus mentioned this issue Jul 9, 2018

Remove rustdoc's plugins feature #52194

Merged

phansch mentioned this issue May 30, 2019

rustdoc: Remove note about deprecated pass configuration rust-lang/rustc-dev-guide#325

Closed

eupn mentioned this issue Jul 28, 2019

Make "see issue" consistent #63008

Closed

dvandra mentioned this issue Sep 29, 2019

[python] Add CVE-2018-1000622 fabric8-analytics/cvedb#6153

Closed

MOZGIII mentioned this issue Sep 3, 2020

Use doc comments to generate the component docs vectordotdev/vector#3698

Closed

camelid mentioned this issue Mar 6, 2021

Add doc(plugins), doc(passes), etc. to INVALID_DOC_ATTRIBUTES #82824

Open

MaxVerevkin mentioned this issue Mar 23, 2021

Discussion: use rustdoc for blocks' documentation greshake/i3status-rust#1127

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tracking issue for rustdoc deprecations/cleanup #44136

Tracking issue for rustdoc deprecations/cleanup #44136

steveklabnik commented Aug 28, 2017 •

edited by jyn514

Loading

BartMassey commented Jun 3, 2018

jonas-schievink commented Aug 22, 2018

QuietMisdreavus commented Aug 23, 2018

jonas-schievink commented Aug 23, 2018

araspik commented Feb 25, 2019 •

edited

Loading

QuietMisdreavus commented Feb 25, 2019

GuillaumeGomez commented Feb 26, 2019

Tracking issue for rustdoc deprecations/cleanup #44136

Tracking issue for rustdoc deprecations/cleanup #44136

Comments

steveklabnik commented Aug 28, 2017 • edited by jyn514 Loading

--input-format/--output-format

--plugin-path/--plugins

--no-defaults/--passes

BartMassey commented Jun 3, 2018

jonas-schievink commented Aug 22, 2018

QuietMisdreavus commented Aug 23, 2018

jonas-schievink commented Aug 23, 2018

araspik commented Feb 25, 2019 • edited Loading

QuietMisdreavus commented Feb 25, 2019

GuillaumeGomez commented Feb 26, 2019

steveklabnik commented Aug 28, 2017 •

edited by jyn514

Loading

`--input-format`/`--output-format`

`--plugin-path`/`--plugins`

`--no-defaults`/`--passes`

araspik commented Feb 25, 2019 •

edited

Loading