Skip to content

Emit errors/warns on some wrong uses of rustdoc attributes #80300

New issue

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

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

Already on GitHub? # to your account

Merged
merged 4 commits into from
May 11, 2021

Conversation

LeSeulArtichaut
Copy link
Contributor

@LeSeulArtichaut LeSeulArtichaut commented Dec 22, 2020

This PR adds a few diagnostics:

  • error if conflicting #[doc(inline)]/#[doc(no_inline)] are found
  • introduce the invalid_doc_attributes lint (warn-by-default) which triggers:
    • if a crate-level attribute is used on a non-crate item
    • if #[doc(inline)]/#[doc(no_inline)] is used on a non-use item

The code could probably be improved but I wanted to get feedback first. Also, some of those changes could be considered breaking changes, so I don't know what the procedure would be? And finally, for the warnings, they are currently hard warnings, maybe it would be better to introduce a lint? (EDIT: introduced the invalid_doc_attributes lint)

Closes #80275.
r? @jyn514

@rust-highfive rust-highfive added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Dec 22, 2020
@jyn514
Copy link
Member

jyn514 commented Dec 22, 2020

I think this should probably go through FCP - I'll take a look at the code first so the review isn't intermingled with the policy change.

Copy link
Member

@jyn514 jyn514 left a comment

Choose a reason for hiding this comment

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

Left a few comments, and I think it would be helpful for @estebank to take a look if you have time.

@rust-log-analyzer

This comment has been minimized.

@LeSeulArtichaut LeSeulArtichaut force-pushed the 80275-doc-inline branch 2 times, most recently from b790ab6 to febf1d5 Compare December 22, 2020 17:33
@rust-log-analyzer

This comment has been minimized.

@GuillaumeGomez
Copy link
Member

Also, it could be interesting to add a macro like https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/macro.struct_span_err.html for warnings (but without error code).

@jyn514
Copy link
Member

jyn514 commented Dec 26, 2020

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@rust-log-analyzer

This comment has been minimized.

@LeSeulArtichaut

This comment has been minimized.

@jyn514 jyn514 added A-diagnostics Area: Messages for errors, warnings, and lints T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-attributes Area: Attributes (`#[…]`, `#![…]`) labels Dec 27, 2020
@LeSeulArtichaut LeSeulArtichaut 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-review Status: Awaiting review from the assignee but also interested parties. labels Dec 27, 2020
@LeSeulArtichaut LeSeulArtichaut added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label May 8, 2021
@jyn514
Copy link
Member

jyn514 commented May 9, 2021

I don't have time to look at this.

r? @Manishearth

@rust-highfive rust-highfive assigned Manishearth and unassigned jyn514 May 9, 2021
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.

Overall looks great, would love to have more doc comments

@LeSeulArtichaut
Copy link
Contributor Author

LeSeulArtichaut commented May 10, 2021

@Manishearth Added a few doc comments in a separate commit. Let me know if you'd want anything else documented.

@Manishearth
Copy link
Member

@bors r+

thanks!

@bors
Copy link
Collaborator

bors commented May 10, 2021

📌 Commit 6e8d0db 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 May 10, 2021
@bors
Copy link
Collaborator

bors commented May 10, 2021

⌛ Testing commit 6e8d0db with merge ac17b18a35f83579e5f75a8da8a7756f4abc9b17...

@rust-log-analyzer

This comment has been minimized.

@bors
Copy link
Collaborator

bors commented May 10, 2021

💔 Test failed - checks-actions

@bors bors added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. and removed S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. labels May 10, 2021
@LeSeulArtichaut
Copy link
Contributor Author

LeSeulArtichaut commented May 10, 2021

This is the only case of invalid #[doc(inline)]/#[doc(no_inline)] I found in std::{os,sys} so we should be good now

@Manishearth
Copy link
Member

@bors r+

@bors
Copy link
Collaborator

bors commented May 11, 2021

📌 Commit 804ab9f 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 May 11, 2021
@bors
Copy link
Collaborator

bors commented May 11, 2021

⌛ Testing commit 804ab9f with merge fe62c6e...

@bors
Copy link
Collaborator

bors commented May 11, 2021

☀️ Test successful - checks-actions
Approved by: Manishearth
Pushing fe62c6e to master...

@bors bors added the merged-by-bors This PR was explicitly merged by bors. label May 11, 2021
@bors bors merged commit fe62c6e into rust-lang:master May 11, 2021
@rustbot rustbot added this to the 1.54.0 milestone May 11, 2021
@LeSeulArtichaut LeSeulArtichaut deleted the 80275-doc-inline branch May 11, 2021 11:04
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
A-attributes Area: Attributes (`#[…]`, `#![…]`) A-diagnostics Area: Messages for errors, warnings, and lints disposition-merge This issue / PR is in PFCP or FCP with a disposition to merge it. finished-final-comment-period The final comment period is finished for this PR / Issue. merged-by-bors This PR was explicitly merged by bors. 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
Development

Successfully merging this pull request may close these issues.

Rustdoc should give an error if you set both doc(inline) and doc(no_inline)