reword

library/std/src/keyword_docs.rs

@@ -2042,14 +2042,19 @@ mod type_keyword {}
 /// system.
 ///
 /// The `unsafe` keyword has two uses:
-/// - to declare the existence of contracts the compiler can't check (`unsafe fn` and `unsafe
-/// trait`),
-/// - and to declare that a programmer has checked that these contracts have been upheld (`unsafe
-/// {}` and `unsafe impl`, but also sometimes `unsafe fn` -- see below).
+/// - to declare the existence of contracts the compiler can't check,
+/// - and to declare that a programmer has checked that these contracts have been upheld.
 ///
-/// Historically, these two are not mutually exclusive, as can be seen in `unsafe fn`: the body of
-/// an `unsafe fn` is, on old editions, treated like an unsafe block. The `unsafe_op_in_unsafe_fn`
-/// lint can be enabled to change that (and that lint is enabled by default since edition 2024).
+/// Typically, each `unsafe` is either of the first or second kind: `unsafe fn` and `unsafe trait`
+/// declare the existence of an unsafe contract; `unsafe {}` and `unsafe impl` declare that an
+/// unsafe contract (which must have been declared elsewhere) is being upheld.
+///
+/// However, historically, these two are not mutually exclusive: the body of an `unsafe fn` is, on
+/// old editions, treated like an unsafe block, which means that this use of `unsafe` both declares
+/// the existence of a contract to call the current function, and declares that the contracts of the
+/// unsafe operations inside this function are being upheld. The `unsafe_op_in_unsafe_fn` lint can
+/// be enabled to change that and make `unsafe fn` only play the former rule. That lint is enabled
+/// by default since edition 2024.
 ///
 /// # Unsafe abilities
 ///