Rollup merge of #152613 - RalfJung:unsafe-keyword-docs, r=traviscross

unsafe keyword docs: bring back unsafe_op_in_unsafe_fn lint discussion

@traviscross in #141471 you asked me to also update the text to account for the edition change. Apparently I did that by entirely removing this part of the discussion (except for a dangling forward reference, a "see below"). Given that old editions still exist and given that `unsafe_op_in_unsafe_fn` is just a lint so the old behavior also still exists on new editions, I am no longer sure that was a good idea, so this brings back the old text with some editing to explain the current situation.

Author: matthiaskrgr

library/std/src/keyword_docs.rs

@@ -2042,10 +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 `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.
+///
+/// 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 role. That lint is enabled
+/// by default since edition 2024.
 ///
 /// # Unsafe abilities
 ///
@@ -2088,6 +2097,13 @@ mod type_keyword {}
 /// - `unsafe impl`: the contract necessary to implement the trait has been
 /// checked by the programmer and is guaranteed to be respected.
 ///
+/// On old editions, `unsafe fn` also acts like an `unsafe {}` block around the code inside the
+/// function. This means it is not just a signal to the caller, but also promises that the
+/// preconditions for the operations inside the function are upheld. Mixing these two meanings can
+/// be confusing, so the `unsafe_op_in_unsafe_fn` lint has been introduced and enabled by default
+/// since edition 2024 to warn against that and require explicit unsafe blocks even inside `unsafe
+/// fn`.
+///
 /// See the [Rustonomicon] and the [Reference] for more information.
 ///
 /// # Examples