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

Rust API Guideline: Unsafe functions are documented with a "Safety" section #2207

Closed
dtolnay opened this issue Nov 5, 2017 · 4 comments · Fixed by #4535
Closed

Rust API Guideline: Unsafe functions are documented with a "Safety" section #2207

dtolnay opened this issue Nov 5, 2017 · 4 comments · Fixed by #4535
Labels
A-lint Area: New lints L-guidelines Lint: Related to the Rust API Guidelines T-AST Type: Requires working with the AST

Comments

@dtolnay
Copy link
Member

dtolnay commented Nov 5, 2017

There should be a "Safety" section that explains all invariants that the caller is responsible for upholding to use the function correctly.

As per Function docs include error, panic, and safety considerations.
@mcarton mcarton mentioned this issue Nov 5, 2017
Open
66 tasks
@phansch phansch added T-AST Type: Requires working with the AST A-lint Area: New lints L-guidelines Lint: Related to the Rust API Guidelines labels Oct 8, 2018
@jeffvandyke
Copy link

I'm surprised that the Rust API Guidelines don't mention unsafe blocks that are usually documented with // SAFETY: ... comments. I think that those comments around unsafe blocks would be a good related lint to do as well.

@dtolnay
Copy link
Member Author

dtolnay commented Sep 10, 2019

Unsafe blocks are not part of the API of a crate, so a recommendation like that is a bit out of scope for the API guidelines. It would be a good "restriction" category lint though.

@llogiq
Copy link
Contributor

llogiq commented Sep 11, 2019

AFAIK, there's a rust PR to have tidy check this for the rust repo. But yes, it would be a good idea to check for this.

@llogiq
Copy link
Contributor

llogiq commented Sep 11, 2019

I'll take this.

@llogiq llogiq mentioned this issue Sep 11, 2019
Merged
bors added a commit that referenced this issue Sep 16, 2019
@bors
Auto merge of #4535 - rust-lang:unsafe-doc, r=flip1995
2ff1202 
New lint: Require `# Safety` section in pub unsafe fn docs

changelog: add `missing_safety_doc` lint

This fixes #2207
flip1995 added a commit to flip1995/rust-clippy that referenced this issue Sep 19, 2019
@flip1995
Rollup merge of rust-lang#4535 - rust-lang:unsafe-doc, r=flip1995
93381fb 
New lint: Require `# Safety` section in pub unsafe fn docs

changelog: add `missing_safety_doc` lint

This fixes rust-lang#2207
@bors bors closed this as completed in f783ff3 Sep 19, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
A-lint Area: New lints L-guidelines Lint: Related to the Rust API Guidelines T-AST Type: Requires working with the AST
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

New lint: Require # Safety section in pub unsafe fn docs rust-lang/rust-clippy
4 participants
@dtolnay @phansch @llogiq @jeffvandyke