Document our usage of Deref

Author: madsmtm

objc2/src/foundation/mod.rs

@@ -21,6 +21,31 @@
 //! [pull requests]: https://github.com/madsmtm/objc2/pulls
 //! [`Message`]: crate::Message
 //! [`msg_send!`]: crate::msg_send
+//!
+//!
+//! # Use of `Deref`
+//!
+//! `objc2::foundation` uses the [`Deref`] trait in a bit special way: All
+//! objects deref to their superclasses. For example, `NSMutableArray` derefs
+//! to `NSArray`, which in turn derefs to `NSObject`.
+//!
+//! Note that this is explicitly recommended against in [the
+//! documentation][`Deref`] and [the Rust Design patterns
+//! book][anti-pattern-deref] (see those links for details).
+//!
+//! Due to Objective-C objects only ever being accessible behind pointers in
+//! the first place, the problems stated there are less severe, and having the
+//! implementation just means that everything is much nicer when you actually
+//! want to use the objects!
+//!
+//! All objects also implement [`AsRef`] and [`AsMut`] to their superclass,
+//! and can be used in [`Id::into_superclass`], so if you favour explicit
+//! conversion, that is a possibility too.
+//!
+//! [`Deref`]: std::ops::Deref
+//! [`ClassType`]: crate::ClassType
+//! [anti-pattern-deref]: https://rust-unofficial.github.io/patterns/anti_patterns/deref.html
+//! [`Id::into_superclass`]: crate::rc::Id::into_superclass
 
 // TODO: Remove these
 #![allow(missing_docs)]