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

Update rustdoc documentation #82690

Merged
merged 1 commit into from
Mar 5, 2021
Merged

Update rustdoc documentation #82690

merged 1 commit into from
Mar 5, 2021

Conversation

jyn514
Copy link
Member

@jyn514 jyn514 commented Mar 2, 2021

  • 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 #82675.

r? @Manishearth

@jyn514 jyn514 added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools labels Mar 2, 2021
@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Mar 2, 2021
jyn514
jyn514 commented Mar 2, 2021
View reviewed changes
src/doc/rustdoc/src/unstable-features.md
@@ -340,6 +340,30 @@ Some methodology notes about what rustdoc counts in this metric:
Public items that are not documented can be seen with the built-in `missing_docs` lint. Private
items that are not documented can be seen with Clippy's `missing_docs_in_private_items` lint.

## `-w`/`--output-format`: output format
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't strictly an unstable option, but it's useless except on nightly, so I moved it here.

Manishearth
Manishearth approved these changes Mar 2, 2021
View reviewed changes
Copy link
Member

@Manishearth Manishearth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

we should really just get rid of passes.md, but i'm fine with a stub so links don't break. Would be nice if it could be hidden from the toc.

@jyn514
Copy link
Member Author

jyn514 commented Mar 2, 2021

Would be nice if it could be hidden from the toc.

Good idea, done :)

@bors r=Manishearth rollup

@bors
Copy link
Contributor

bors commented Mar 2, 2021

📌 Commit a762374e4e571b1cefd3ddca06c12adc3c90df56 has been approved by Manishearth

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Mar 2, 2021
@rust-log-analyzer

This comment has been minimized.

Sign in to view
@jyn514
Copy link
Member Author

jyn514 commented Mar 2, 2021

@bors r-

Apparently removing it from the table of the contents causes it not to get built (??)

@bors bors added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels Mar 2, 2021
poliorcetics
poliorcetics reviewed Mar 2, 2021
View reviewed changes
src/doc/rustdoc/src/command-line-arguments.md
}
```

`--document-private-items` documents all items, even if they're not public.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe a note on the fact it is very useful when developing the library or binary crate that is being documented, not as a user of said library/binary ? I don't know if that's a good place to put such a tip

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, does that need explanation? It seems pretty self-evident to me.

@rust-log-analyzer

This comment has been minimized.

Sign in to view
@jyn514
Update rustdoc documentation
dbdaa12 
- 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.
- Move `passes.html` to the end of the table of contents. Ideally it
  would be removed altogether, but that causes mdbook not to generate the
  docs.
@jyn514
Copy link
Member Author

jyn514 commented Mar 4, 2021 •
edited
Loading

Apparently removing it from the table of the contents causes it not to get built (??)

I added it back for now (at the very end, so you don't see it in the middle of reading the book). @poliorcetics I haven't forgotten your comment, but I think it can be addressed in a follow-up if need be.

@bors r=Manishearth rollup

@bors
Copy link
Contributor

bors commented Mar 4, 2021

📌 Commit dbdaa12 has been approved by Manishearth

@bors bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Mar 4, 2021
@GuillaumeGomez GuillaumeGomez mentioned this pull request Mar 4, 2021
Merged
Dylan-DPC-zz pushed a commit to Dylan-DPC-zz/rust that referenced this pull request 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``
@Dylan-DPC-zz Dylan-DPC-zz mentioned this pull request Mar 5, 2021
Closed
JohnTitor added a commit to JohnTitor/rust that referenced this pull request 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```
@JohnTitor JohnTitor mentioned this pull request Mar 5, 2021
Closed
bors added a commit to rust-lang-ci/rust that referenced this pull request Mar 5, 2021
@bors
Auto merge of rust-lang#82777 - GuillaumeGomez:rollup-etcsupl, r=Guil…
8ccc89b 
…laumeGomez

Rollup of 5 pull requests

Successful merges:

 - rust-lang#76716 (Don't warn for `missing_doc_examples` when item is #[doc(hidden)])
 - rust-lang#82088 (Shorten html::render)
 - rust-lang#82690 (Update rustdoc documentation)
 - rust-lang#82752 (Add a regression test for issue-81712)
 - rust-lang#82765 (Fix polymorphization ICE on associated types in trait decls using const generics in bounds)

Failed merges:

r? `@ghost`
`@rustbot` modify labels: rollup
m-ou-se added a commit to m-ou-se/rust that referenced this pull request 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````
@m-ou-se m-ou-se mentioned this pull request Mar 5, 2021
Closed
@bors bors merged commit 2a5ecb2 into rust-lang:master Mar 5, 2021
@rustbot rustbot added this to the 1.52.0 milestone Mar 5, 2021
@jyn514 jyn514 deleted the remove-pass-docs branch March 5, 2021 13:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@poliorcetics poliorcetics poliorcetics left review comments

@Manishearth Manishearth Manishearth approved these changes

Assignees

@Manishearth Manishearth

Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Milestone
1.52.0
Development

Successfully merging this pull request may close these issues.

Document no_default_passes attribute or remove documentation for --passes and --no-default-passes?
7 participants
@jyn514 @bors @rust-log-analyzer @Manishearth @poliorcetics @rust-highfive @rustbot