soft-deprecate the addr_of macros

Author: RalfJung

library/core/src/ptr/mod.rs

@@ -2136,6 +2136,9 @@ impl<F: FnPtr> fmt::Debug for F {
 
 /// Create a `const` raw pointer to a place, without creating an intermediate reference.
 ///
+/// `addr_of!(expr)` is equivalent to `&raw const expr`. The macro is *soft-deprecated*;
+/// use `&raw const` instead.
+///
 /// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned
 /// and points to initialized data. For cases where those requirements do not hold,
 /// raw pointers should be used instead. However, `&expr as *const _` creates a reference
@@ -2210,6 +2213,9 @@ pub macro addr_of($place:expr) {
 
 /// Create a `mut` raw pointer to a place, without creating an intermediate reference.
 ///
+/// `addr_of_mut!(expr)` is equivalent to `&raw mut expr`. The macro is *soft-deprecated*;
+/// use `&raw mut` instead.
+///
 /// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned
 /// and points to initialized data. For cases where those requirements do not hold,
 /// raw pointers should be used instead. However, `&mut expr as *mut _` creates a reference