Clarify Id::retain safety when T is not 'static

Author: madsmtm

objc2/src/rc/id.rs

@@ -175,12 +175,14 @@ impl<T: Message + ?Sized, O: Ownership> Id<T, O> {
     ///
     /// Returns `None` if the pointer was null.
     ///
+    ///
     /// # Safety
     ///
     /// The caller must ensure the given object has +1 retain count, and that
     /// the object pointer otherwise follows the same safety requirements as
     /// in [`Id::retain`].
     ///
+    ///
     /// # Example
     ///
     /// ```no_run
@@ -309,6 +311,7 @@ impl<T: Message, O: Ownership> Id<T, O> {
     ///
     /// Returns `None` if the pointer was null.
     ///
+    ///
     /// # Safety
     ///
     /// The caller must ensure that the ownership is correct; that is, there
@@ -320,6 +323,10 @@ impl<T: Message, O: Ownership> Id<T, O> {
     /// dereferencable and initialized, see the [`std::ptr`] module for more
     /// information).
     ///
+    /// Finally, if you do not know the concrete type of `T`, it may not be
+    /// `'static`, and hence you must ensure that the data that `T` references
+    /// lives for as long as `T`.
+    ///
     /// [`std::ptr`]: core::ptr
     //
     // This would be illegal:
@@ -580,13 +587,17 @@ impl<T: Message> Id<T, Owned> {
 
     /// Promote a shared [`Id`] to an owned one, allowing it to be mutated.
     ///
+    ///
     /// # Safety
     ///
     /// The caller must ensure that there are no other pointers (including
     /// [`WeakId`][`super::WeakId`] pointers) to the same object.
     ///
     /// This also means that the given [`Id`] should have a retain count of
     /// exactly 1 (except when autoreleases are involved).
+    ///
+    /// In general, this is wildly unsafe, do see if you can find a different
+    /// solution!
     #[inline]
     pub unsafe fn from_shared(obj: Id<T, Shared>) -> Self {
         // Note: We can't debug_assert retainCount because of autoreleases