Detect inconsistent "style" for safety-related docs/comments

[ojeda]

What it does

Projects typically use a single convention for safety docs and comments, typically # Safety sections in docs and // SAFETY: comments. However, it is possible for developers to mix up the two styles from time to time. It would be useful to have a lint that detects that.

When combined with other safety-related Clippy lints, this becomes extra effective. For instance, we had a case in Linux of safe functions that should have been unsafe fn: the safety "section" was there but using the incorrect style, and thus Clippy didn't lint about it.

The other safety-related lints may be enough to cover all cases (or extending them otherwise). For instance, if #15034 is a false negative (i.e. if that lint is supposed to catch even the /// case and not just //) and it is fixed, then we would have caught the case in the patch above. Thus this lint may be unneeded for projects that enable all the safety-related lints.

Advantage

• May actually catch extra issues when combined with other safety-related lints (please see above).
• More consistency in docs.
• Less time spent by reviewers.

Drawbacks

No response

Example

/// SAFETY: ...
fn f() {}

Should be written as:

/// # Safety
///
/// ...
fn f() {}

Note that the lint should trigger even if the function is safe, because that allows the other safety-related lints to detect other mistakes (please see above).

Similarly:

fn f() {
    // # Safety
    //
    // ...
    unsafe { g() }
}

Should be written as:

fn f() {
    /// SAFETY: ...
    unsafe { g() }
}