Document a few quick observations

Author: madsmtm

objc2-encode/src/encode.rs

@@ -147,6 +147,8 @@ pub unsafe trait RefEncode {
     const ENCODING_REF: Encoding<'static>;
 }
 
+// TODO: Implement for `PhantomData` and `PhantomPinned`?
+
 /// Simple helper for implementing [`Encode`].
 macro_rules! encode_impls {
     ($($t:ty => $e:ident,)*) => ($(
@@ -318,6 +320,7 @@ unsafe impl<T: RefEncode + ?Sized> RefEncode for ManuallyDrop<T> {
 // core::cell::Ref?
 // core::cell::RefCell?
 // core::cell::RefMut?
+// core::panic::AssertUnwindSafe<T>
 
 // SAFETY: `Pin` is `repr(transparent)`.
 unsafe impl<T: Encode> Encode for Pin<T> {
@@ -341,6 +344,8 @@ unsafe impl<T: RefEncode> RefEncode for Wrapping<T> {
     const ENCODING_REF: Encoding<'static> = T::ENCODING_REF;
 }
 
+// TODO: core::num::Saturating when that is stabilized
+
 // TODO: core::cmp::Reverse?
 
 /// Helper for implementing `Encode`/`RefEncode` for pointers to types that

objc2/src/exception.rs

@@ -37,6 +37,11 @@ extern "C" {
     /// (and would probably give us a bit better performance), but it gets
     /// unwieldy _very_ quickly, so I chose the much more stable option.
     ///
+    /// Another thing to remember: While Rust's and Objective-C's unwinding
+    /// mechanisms are similar now, Rust's is explicitly unspecified, and they
+    /// may diverge significantly in the future; so handling this in pure Rust
+    /// (using mechanisms like core::intrinsics::r#try) is not an option!
+    ///
     /// [manual-asm]: https://gitlab.com/objrs/objrs/-/blob/b4f6598696b3fa622e6fddce7aff281770b0a8c2/src/exception.rs
     fn rust_objc_try_catch_exception(
         f: extern "C" fn(*mut c_void),

objc2/src/rc/autorelease.rs

@@ -18,6 +18,8 @@ use crate::ffi;
 /// pool on the current thread.
 #[derive(Debug)]
 pub struct AutoreleasePool {
+    /// This is an opaque handle, and is not guaranteed to be neither a valid
+    /// nor aligned pointer.
     context: *mut c_void,
     // May pointer to data that is mutated (even though we hold shared access)
     p: PhantomData<*mut UnsafeCell<c_void>>,
@@ -140,9 +142,13 @@ impl Drop for AutoreleasePool {
     /// > Not draining the pool during an unwind is apparently required by the
     /// > Objective-C exceptions implementation.
     ///
-    /// This was true in the past, but since [revision `371`] of objc4 (ships
-    /// with MacOS 10.5) the exception is now retained when `@throw` is
-    /// encountered.
+    /// However, we would like to do this anyway whenever possible, since the
+    /// unwind is probably caused by Rust, and forgetting to pop the pool will
+    /// likely leak memory.
+    ///
+    /// Fortunately, the above statement was true in the past, but since
+    /// [revision `371`] of objc4 (ships with MacOS 10.5) the exception is now
+    /// retained when `@throw` is encountered.
     ///
     /// Hence it is safe to drain the pool when unwinding.
     ///

objc2/src/rc/weak_id.rs

@@ -25,6 +25,7 @@ pub struct WeakId<T: ?Sized> {
     /// an UnsafeCell to get a *mut without self being mutable.
     ///
     /// TODO: Verify the need for UnsafeCell?
+    /// TODO: Investigate if we can avoid some allocations using `Pin`.
     inner: Box<UnsafeCell<*mut T>>,
     /// WeakId inherits variance, dropck and various marker traits from
     /// `Id<T, Shared>` because it can be upgraded to a shared Id.