include note on variance and example

Fixes #89150

Author: hkBst

library/core/src/any.rs

@@ -610,6 +610,84 @@ impl dyn Any + Send + Sync {
 /// While `TypeId` implements `Hash`, `PartialOrd`, and `Ord`, it is worth
 /// noting that the hashes and ordering will vary between Rust releases. Beware
 /// of relying on them inside of your code!
+///
+/// **Note on Variance**:
+/// Suppose `SubType` is a subtype of `SuperType`,
+/// that is, `SubType` can be used wherever `SuperType` can be used,
+/// and can be freely as-casted to it,
+/// and `CoVar`is a generic data type that has a covariant type parameter.
+/// Then by covariance, `CoVar<SubType>` is a subtype of `CoVar<SuperType>`,
+/// that is, `CoVar<SubType>` can be used wherever `CoVar<SuperType>` can be used,
+/// and can be freely as-casted to it.
+/// Then if `CoVar<SuperType>` relies on `TypeId::of::<SuperType>` to uphold any invariants,
+/// those invariants may be broken like so:
+/// ```
+/// type SubType = fn(&());
+/// type SuperType = fn(&'static ());
+/// type CoVar<T> = *const T; // imagine something more complicated
+///
+/// let sub = CoVar::<SubType>::new();
+/// // not created by CoVar::<SuperType>::new
+/// let fake_super = sub as CoVar<SuperType>;
+/// ```
+///
+/// A full example
+///
+/// ```
+/// use std::any::TypeId;
+/// use std::collections::HashSet;
+/// use std::marker::PhantomData;
+/// use std::sync::{LazyLock, Mutex};
+///
+/// use unique::Unique;
+///
+/// static ID_SET: LazyLock<Mutex<HashSet<TypeId>>> = LazyLock::new(|| Mutex::new(HashSet::new()));
+///
+/// mod unique {
+///     use super::*;
+///
+///     // Due to its private data member, outside this module,
+///     // this struct can only be created using `new`.
+///     #[derive(Debug, PartialEq)]
+///     pub struct Unique<TypeAsId: 'static>(PhantomData<TypeAsId>);
+///
+///     impl<TypeAsId: 'static> Unique<TypeAsId> {
+///         pub fn new() -> Option<Self> {
+///             let mut set = ID_SET.lock().unwrap();
+///             set.insert(TypeId::of::<TypeAsId>())
+///                 .then(|| Self(PhantomData))
+///         }
+///     }
+///
+///     impl<TypeAsId: 'static> Drop for Unique<TypeAsId> {
+///         fn drop(&mut self) {
+///             let mut set = ID_SET.lock().unwrap();
+///             (!set.remove(&TypeId::of::<TypeAsId>())).then(|| panic!("duplicity detected"));
+///         }
+///     }
+/// }
+///
+/// // A FnRef can be used wherever a FnStaticRef can be used,
+/// // so FnRef is a subtype of FnStaticRef.
+/// // Both are 'static, and thus have a TypeId.
+/// type FnRef = fn(&());
+/// type FnStaticRef = fn(&'static ());
+///
+/// fn main() {
+///     type TheOneRing = FnStaticRef;
+///
+///     let the_one_ring = Unique::<TheOneRing>::new().unwrap();
+///     assert_eq!(Unique::<TheOneRing>::new(), None);
+///
+///     type OtherRing = FnRef;
+///
+///     let other_ring = Unique::<OtherRing>::new().unwrap();
+///     let fake_one_ring = other_ring as Unique<TheOneRing>;
+///     assert_eq!(fake_one_ring, the_one_ring);
+///
+///     std::mem::forget(fake_one_ring);
+/// }
+/// ```
 #[derive(Clone, Copy, Eq, PartialOrd, Ord)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct TypeId {
@@ -627,8 +705,7 @@ impl PartialEq for TypeId {
 }
 
 impl TypeId {
-    /// Returns the `TypeId` of the type this generic function has been
-    /// instantiated with.
+    /// Given a type (as a generic type argument), returns the `TypeId` of that type.
     ///
     /// # Examples
     ///