Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tracking issue for rustdoc deprecations/cleanup #44136

Closed
steveklabnik opened this issue Aug 28, 2017 · 7 comments

Comments

Projects
None yet
6 participants
@steveklabnik
Copy link
Member

commented Aug 28, 2017

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.

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

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

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

frewsxcv added a commit to frewsxcv/rust that referenced this issue Aug 29, 2017

Rollup merge of rust-lang#44138 - steveklabnik:rustdoc-deprecations, …
…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...

frewsxcv added a commit to frewsxcv/rust that referenced this issue Aug 29, 2017

Rollup merge of rust-lang#44138 - steveklabnik:rustdoc-deprecations, …
…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...

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

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 1, 2017

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 1, 2017

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 21, 2017

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 21, 2017

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 21, 2017

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 21, 2017

steveklabnik added a commit to steveklabnik/rust that referenced this issue Sep 21, 2017

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

kennytm added a commit to kennytm/rust that referenced this issue Oct 18, 2017

Rollup merge of rust-lang#44138 - steveklabnik:rustdoc-deprecations, …
…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...

kennytm added a commit to kennytm/rust that referenced this issue May 16, 2018

Rollup merge of rust-lang#50669 - QuietMisdreavus:deprecated-attrs, r…
…=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

This comment has been minimized.

Copy link

commented Jun 3, 2018

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

This comment has been minimized.

Copy link
Member

commented Aug 22, 2018

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

This comment has been minimized.

Copy link
Member

commented Aug 23, 2018

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

@jonas-schievink

This comment has been minimized.

Copy link
Member

commented Aug 23, 2018

@QuietMisdreavus Great, thanks!

@araspik

This comment has been minimized.

Copy link

commented Feb 25, 2019

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

This comment has been minimized.

Copy link
Member

commented Feb 25, 2019

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

This comment has been minimized.

Copy link
Member

commented Feb 26, 2019

I'll *soon* though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.