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

[dtolnay]

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.

[jeffvandyke]

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]

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]

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]

I'll take this.