Document weak properties

We also link to this documentation from the property setters themselves.

This is a common point of confusion, see:
- #585
- #606
- https://matrix.to/#/!SrJvHgAPHenBakQHSz:matrix.org/$OsgLE1-VtAZ5f383z_UoEpDyS7xDUk67xveA_zWvyZA?via=matrix.org

crates/header-translator/src/method.rs

@@ -258,6 +258,7 @@ pub struct Method {
     // Thread-safe, even on main-thread only (@MainActor/@UIActor) classes
     non_isolated: bool,
     mainthreadonly: bool,
+    weak_property: bool,
 }
 
 #[derive(Debug)]
@@ -505,6 +506,7 @@ impl Method {
                 is_pub,
                 non_isolated: modifiers.non_isolated,
                 mainthreadonly,
+                weak_property: false,
             },
         ))
     }
@@ -577,6 +579,8 @@ impl Method {
                 is_pub,
                 non_isolated: modifiers.non_isolated,
                 mainthreadonly,
+                // Don't show `weak`-ness on getters
+                weak_property: false,
             })
         } else {
             None
@@ -619,6 +623,7 @@ impl Method {
                     is_pub,
                     non_isolated: modifiers.non_isolated,
                     mainthreadonly,
+                    weak_property: attributes.map(|a| a.weak).unwrap_or(false),
                 })
             } else {
                 None
@@ -666,6 +671,13 @@ impl fmt::Display for Method {
         //     writeln!(f, "// non_isolated")?;
         // }
 
+        if self.weak_property {
+            writeln!(
+                f,
+                "        /// This is a [weak property][objc2::topics::weak_property]."
+            )?;
+        }
+
         //
         // Attributes
         //

crates/objc2/src/topics/mod.rs

@@ -16,6 +16,8 @@ pub mod layered_safety {}
 pub mod mvc {}
 #[doc = include_str!("interior_mutability.md")]
 pub mod interior_mutability {}
+#[doc = include_str!("weak_property.md")]
+pub mod weak_property {} // Referenced by header-translator
 #[cfg(not(feature = "gnustep-1-7"))]
 #[doc = include_str!("run_loop.md")]
 pub mod run_loop {}

crates/objc2/src/topics/weak_property.md

@@ -0,0 +1,12 @@
+# Weak properties
+
+Delegates in Cocoa are often stored as [`rc::Weak`] properties, to avoid reference cycles when the delegate also wants to store the object it is the delegate of.
+
+This can be a bit confusing sometimes if you create a delegate, set it on an object, and then expect your delegate methods to be called later on (which they in reality won't since the delegate will have been deallocated).
+
+In practice, you will have to store your delegate objects somewhere else, for example in your top-level application delegate.
+
+See Apple's [documentation on weak references][mem-weak] for a few more details.
+
+[`rc::Weak`]: crate::rc::Weak
+[mem-weak]: https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MemoryMgmt/Articles/mmPractical.html#//apple_ref/doc/uid/TP40004447-1000810