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.

Sign up for GitHub

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

Jump to bottom

Document no_default_passes attribute or remove documentation for --passes and --no-default-passes? #82675

Closed
GuillaumeGomez opened this issue Mar 1, 2021 · 5 comments · Fixed by #82690
Closed

Document no_default_passes attribute or remove documentation for --passes and --no-default-passes? #82675

GuillaumeGomez opened this issue Mar 1, 2021 · 5 comments · Fixed by #82690
Assignees
@jyn514
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@GuillaumeGomez
Copy link
Member

From #82662 (comment).

The whole https://doc.rust-lang.org/nightly/rustdoc/passes.html chapter looks questionable now that customizing passes is deprecated.

So not sure which way seems better? What do you think @rust-lang/rustdoc ?
@GuillaumeGomez GuillaumeGomez added the T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. label Mar 1, 2021
@jyn514 jyn514 added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Mar 1, 2021
@Manishearth
Copy link
Member

Yeah I think we should document the new stuff and remove the docs for the deprecated stuff (perhaps mention that these deprecated features exist, but not document them in depth)

@camelid
Copy link
Member

camelid commented Mar 2, 2021

I've felt confused about this before: Why do we even let people customize which passes are run? That seems like unnecessary entanglement with rustdoc internals.

@camelid
Copy link
Member

camelid commented Mar 2, 2021 •
edited
Loading

Also, there doesn't seem to be a --no-default-passes flag. Are you thinking of --no-defaults? If so, rustdoc says that's deprecated.

Edit: It looks like --passes is deprecated as well.

@camelid
Copy link
Member

camelid commented Mar 2, 2021 •
edited
Loading

Yeah I think we should document the new stuff and remove the docs for the deprecated stuff (perhaps mention that these deprecated features exist, but not document them in depth)

What is "the new stuff"? Do you mean things like --document-private-items? Other than my confusion about that, I agree with Manish here. I think we should mention the deprecated features, but not document them extensively since they shouldn't be used anyway. If we extensively document deprecated features, we are wasting our time and our readers' time.

@Manishearth
Copy link
Member

What is "the new stuff"? Do you mean things like --document-private-items?

Yes.

I do think the pass infra should stay mostly internal, with specific options being exposed via specific attributes. How we construct it internally should not be something the user should ever have to care about.

@jyn514 jyn514 self-assigned this Mar 2, 2021
@jyn514 jyn514 mentioned this issue Mar 2, 2021
Merged
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this issue Mar 5, 2021
@Dylan-DPC
Rollup merge of rust-lang#82690 - jyn514:remove-pass-docs, r=Manishearth
2f5409a 
Update rustdoc documentation

- Remove most of the information about passes. Passes are deprecated.
- Add `--document-private-items`; it was missing before.
- Update `--output-format json`; it was very outdated.
- Note that `--input-format` is deprecated.
- Move deprecated options to the very end.

Closes rust-lang#82675.

r? ``@Manishearth``
JohnTitor added a commit to JohnTitor/rust that referenced this issue Mar 5, 2021
@JohnTitor
Rollup merge of rust-lang#82690 - jyn514:remove-pass-docs, r=Manishearth
65943f7 
Update rustdoc documentation

- Remove most of the information about passes. Passes are deprecated.
- Add `--document-private-items`; it was missing before.
- Update `--output-format json`; it was very outdated.
- Note that `--input-format` is deprecated.
- Move deprecated options to the very end.

Closes rust-lang#82675.

r? ```@Manishearth```
m-ou-se added a commit to m-ou-se/rust that referenced this issue Mar 5, 2021
@m-ou-se
Rollup merge of rust-lang#82690 - jyn514:remove-pass-docs, r=Manishearth
729353a 
Update rustdoc documentation

- Remove most of the information about passes. Passes are deprecated.
- Add `--document-private-items`; it was missing before.
- Update `--output-format json`; it was very outdated.
- Note that `--input-format` is deprecated.
- Move deprecated options to the very end.

Closes rust-lang#82675.

r? ````@Manishearth````
@bors bors closed this as completed in 2a5ecb2 Mar 5, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@jyn514 jyn514

Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Update rustdoc documentation jyn514/rust
4 participants
@Manishearth @GuillaumeGomez @jyn514 @camelid