Apply suggestions from code review

Co-authored-by: Daniel Henry-Mantilla <[email protected]>

Author: hkBst

library/core/src/any.rs

@@ -611,7 +611,27 @@ impl dyn Any + Send + Sync {
 /// noting that the hashes and ordering will vary between Rust releases. Beware
 /// of relying on them inside of your code!
 ///
-/// **Note on Variance**:
+/// # Remarks and gotchas around `unsafe` code
+///
+/// ## Variance
+///
+/// A generic `<T: 'static>` type is still susceptible to variance,
+/// since there exist distinct types in a subtyping relationship
+/// which nonetheless are very much `: 'static`.
+///
+/// For instance:
+///   - `T = fn(&str) = for<'any> fn(&'any str)`, and
+///   - `U = fn(&'static str)`
+/// are both distinct, `: 'static`, and yet `T` is a subtype of `U`.
+///
+/// This means that abstractions around `TypeId`, despite its
+/// `: 'static` requirement, still need to worry about unnecessary
+/// and improper variance: it is advisable to strive for invariance
+/// first. The usability impact will be negligible, while the reduction
+/// in the risk of unsoundness will be most welcome.
+///
+/// ### Illustration of improper variance
+///
 /// Suppose `SubType` is a subtype of `SuperType`, that is,
 /// values of type `SubType` can be used wherever `SuperType` is
 /// expected (so they can, for instance, be freely `as`-casted to it).
@@ -713,7 +733,7 @@ impl PartialEq for TypeId {
 }
 
 impl TypeId {
-    /// Given a type (as a generic type argument), returns the `TypeId` of that type.
+    /// Returns the `TypeId` of the generic type parameter.
     ///
     /// # Examples
     ///