Various documentation fixes and cleanups

- Make a few `where` clauses simpler
- Remove unnecessary `fn main` from doctests
- Fix a bunch of item links
- Document `objc::Message` better
- Refactor `Object` impl a bit

Author: madsmtm

objc/src/cache.rs

@@ -4,14 +4,14 @@ use core::sync::atomic::{AtomicPtr, Ordering};
 
 use crate::runtime::{self, Class, Sel};
 
-/// Allows storing a `Sel` in a static and lazily loading it.
+/// Allows storing a [`Sel`] in a static and lazily loading it.
 #[doc(hidden)]
 pub struct CachedSel {
     ptr: AtomicPtr<c_void>,
 }
 
 impl CachedSel {
-    /// Constructs a new `CachedSel`.
+    /// Constructs a new [`CachedSel`].
     pub const fn new() -> CachedSel {
         CachedSel {
             ptr: AtomicPtr::new(ptr::null_mut()),
@@ -35,14 +35,14 @@ impl CachedSel {
     }
 }
 
-/// Allows storing a `Class` reference in a static and lazily loading it.
+/// Allows storing a [`Class`] reference in a static and lazily loading it.
 #[doc(hidden)]
 pub struct CachedClass {
     ptr: AtomicPtr<Class>,
 }
 
 impl CachedClass {
-    /// Constructs a new `CachedClass`.
+    /// Constructs a new [`CachedClass`].
     pub const fn new() -> CachedClass {
         CachedClass {
             ptr: AtomicPtr::new(ptr::null_mut()),

objc/src/declare.rs

@@ -1,7 +1,7 @@
 /*!
 Functionality for declaring Objective-C classes.
 
-Classes can be declared using the `ClassDecl` struct. Instance variables and
+Classes can be declared using the [`ClassDecl`] struct. Instance variables and
 methods can then be added before the class is ultimately registered.
 
 # Example
@@ -13,7 +13,6 @@ one ivar, a `u32` named `_number` and a `number` method that returns it:
 # use objc::{class, sel};
 # use objc::declare::ClassDecl;
 # use objc::runtime::{Class, Object, Sel};
-# fn main() {
 let superclass = class!(NSObject);
 let mut decl = ClassDecl::new("MyNumber", superclass).unwrap();
 
@@ -30,7 +29,6 @@ unsafe {
 }
 
 decl.register();
-# }
 ```
 */
 
@@ -52,7 +50,7 @@ pub trait MethodImplementation {
     /// The argument types of the method.
     type Args: EncodeArguments;
 
-    /// Returns self as an `Imp` of a method.
+    /// Returns self as an [`Imp`] of a method.
     fn imp(self) -> Imp;
 }
 
@@ -129,20 +127,21 @@ impl ClassDecl {
         }
     }
 
-    /// Constructs a `ClassDecl` with the given name and superclass.
-    /// Returns `None` if the class couldn't be allocated.
+    /// Constructs a [`ClassDecl`] with the given name and superclass.
+    ///
+    /// Returns [`None`] if the class couldn't be allocated.
     pub fn new(name: &str, superclass: &Class) -> Option<ClassDecl> {
         ClassDecl::with_superclass(name, Some(superclass))
     }
 
     /**
-    Constructs a `ClassDecl` declaring a new root class with the given name.
-    Returns `None` if the class couldn't be allocated.
+    Constructs a [`ClassDecl`] declaring a new root class with the given name.
+    Returns [`None`] if the class couldn't be allocated.
 
     An implementation for `+initialize` must also be given; the runtime calls
     this method for all classes, so it must be defined on root classes.
 
-    Note that implementing a root class is not a simple endeavor.
+    Note that implementing a root class is not a simple endeavor!
     For example, your class probably cannot be passed to Cocoa code unless
     the entire `NSObject` protocol is implemented.
     Functionality it expects, like implementations of `-retain` and `-release`
@@ -158,9 +157,12 @@ impl ClassDecl {
         decl
     }
 
-    /// Adds a method with the given name and implementation to self.
-    /// Panics if the method wasn't sucessfully added
-    /// or if the selector and function take different numbers of arguments.
+    /// Adds a method with the given name and implementation.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the method wasn't sucessfully added or if the selector and
+    /// function take different numbers of arguments.
     ///
     /// # Safety
     ///
@@ -184,9 +186,12 @@ impl ClassDecl {
         assert!(success != NO, "Failed to add method {:?}", sel);
     }
 
-    /// Adds a class method with the given name and implementation to self.
-    /// Panics if the method wasn't sucessfully added
-    /// or if the selector and function take different numbers of arguments.
+    /// Adds a class method with the given name and implementation.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the method wasn't sucessfully added or if the selector and
+    /// function take different numbers of arguments.
     ///
     /// # Safety
     ///
@@ -211,12 +216,12 @@ impl ClassDecl {
         assert!(success != NO, "Failed to add class method {:?}", sel);
     }
 
-    /// Adds an ivar with type `T` and the provided name to self.
-    /// Panics if the ivar wasn't successfully added.
-    pub fn add_ivar<T>(&mut self, name: &str)
-    where
-        T: Encode,
-    {
+    /// Adds an ivar with type `T` and the provided name.
+    ///
+    /// # Panics
+    ///
+    /// If the ivar wasn't successfully added.
+    pub fn add_ivar<T: Encode>(&mut self, name: &str) {
         let c_name = CString::new(name).unwrap();
         let encoding = CString::new(T::ENCODING.to_string()).unwrap();
         let size = mem::size_of::<T>();
@@ -227,15 +232,18 @@ impl ClassDecl {
         assert!(success != NO, "Failed to add ivar {}", name);
     }
 
-    /// Adds a protocol to self. Panics if the protocol wasn't successfully
-    /// added
+    /// Adds the given protocol to self.
+    ///
+    /// # Panics
+    ///
+    /// If the protocol wasn't successfully added.
     pub fn add_protocol(&mut self, proto: &Protocol) {
         let success = unsafe { runtime::class_addProtocol(self.cls, proto) };
         assert!(success != NO, "Failed to add protocol {:?}", proto);
     }
 
-    /// Registers self, consuming it and returning a reference to the
-    /// newly registered `Class`.
+    /// Registers the [`ClassDecl`], consuming it, and returns a reference to
+    /// the newly registered [`Class`].
     pub fn register(self) -> &'static Class {
         unsafe {
             let cls = self.cls;
@@ -262,8 +270,9 @@ pub struct ProtocolDecl {
 }
 
 impl ProtocolDecl {
-    /// Constructs a `ProtocolDecl` with the given name. Returns `None` if the
-    /// protocol couldn't be allocated.
+    /// Constructs a [`ProtocolDecl`] with the given name.
+    ///
+    /// Returns [`None`] if the protocol couldn't be allocated.
     pub fn new(name: &str) -> Option<ProtocolDecl> {
         let c_name = CString::new(name).unwrap();
         let proto = unsafe { runtime::objc_allocateProtocol(c_name.as_ptr()) };
@@ -303,7 +312,7 @@ impl ProtocolDecl {
         }
     }
 
-    /// Adds an instance method declaration with a given description to self.
+    /// Adds an instance method declaration with a given description.
     pub fn add_method_description<Args, Ret>(&mut self, sel: Sel, is_required: bool)
     where
         Args: EncodeArguments,
@@ -312,7 +321,7 @@ impl ProtocolDecl {
         self.add_method_description_common::<Args, Ret>(sel, is_required, true)
     }
 
-    /// Adds a class method declaration with a given description to self.
+    /// Adds a class method declaration with a given description.
     pub fn add_class_method_description<Args, Ret>(&mut self, sel: Sel, is_required: bool)
     where
         Args: EncodeArguments,
@@ -328,8 +337,8 @@ impl ProtocolDecl {
         }
     }
 
-    /// Registers self, consuming it and returning a reference to the
-    /// newly registered `Protocol`.
+    /// Registers the [`ProtocolDecl`], consuming it and returning a reference
+    /// to the newly registered [`Protocol`].
     pub fn register(self) -> &'static Protocol {
         unsafe {
             runtime::objc_registerProtocol(self.proto);

objc/src/encode.rs

@@ -22,7 +22,7 @@ unsafe impl<'a> Encode for &'a mut Class {
 }
 
 /// Types that represent a group of arguments, where each has an Objective-C
-/// type encoding.
+/// type-encoding.
 pub trait EncodeArguments {
     /// The type as which the encodings for Self will be returned.
     const ENCODINGS: &'static [Encoding<'static>];

objc/src/exception.rs

@@ -1,5 +1,3 @@
-use objc_exception;
-
 use crate::rc::StrongPtr;
 use crate::runtime::Object;
 
@@ -20,9 +18,6 @@ use crate::runtime::Object;
 /// undefined behaviour until `C-unwind` is stabilized, see [RFC-2945].
 ///
 /// [RFC-2945]: https://rust-lang.github.io/rfcs/2945-c-unwind-abi.html
-pub unsafe fn catch_exception<F, R>(closure: F) -> Result<R, StrongPtr>
-where
-    F: FnOnce() -> R,
-{
+pub unsafe fn catch_exception<R>(closure: impl FnOnce() -> R) -> Result<R, StrongPtr> {
     objc_exception::r#try(closure).map_err(|exception| StrongPtr::new(exception as *mut Object))
 }

objc/src/lib.rs

@@ -8,7 +8,6 @@ Objective-C objects can be messaged using the [`msg_send!`](macro.msg_send!.html
 ``` no_run
 # use objc::{class, msg_send};
 # use objc::runtime::{BOOL, Class, Object};
-# fn main() {
 # unsafe {
 let cls = class!(NSObject);
 let obj: *mut Object = msg_send![cls, new];
@@ -17,7 +16,6 @@ let is_kind: BOOL = msg_send![obj, isKindOfClass:cls];
 // Even void methods must have their return type annotated
 let _: () = msg_send![obj, release];
 # }
-# }
 ```
 
 # Reference counting

objc/src/macros.rs

@@ -1,15 +1,20 @@
 /**
-Gets a reference to a `Class`.
+Gets a reference to a [`Class`] from the given name.
+
+# Panics
 
 Panics if no class with the given name can be found.
-To check for a class that may not exist, use `Class::get`.
 
-# Example
+To check for a class that may not exist, use [`Class::get`].
+
+[`Class`]: crate::runtime::Class
+[`Class::get`]: crate::runtime::Class::get
+
+# Examples
+
 ``` no_run
 # use objc::class;
-# fn main() {
 let cls = class!(NSObject);
-# }
 ```
 */
 #[macro_export]
@@ -27,15 +32,18 @@ macro_rules! class {
 }
 
 /**
-Registers a selector, returning a `Sel`.
+Registers a selector with the Objective-C runtime.
+
+Returns a [`Sel`].
+
+[`Sel`]: crate::runtime::Sel
+
+# Examples
 
-# Example
 ```
 # use objc::sel;
-# fn main() {
 let sel = sel!(description);
 let sel = sel!(setObject:forKey:);
-# }
 ```
 */
 #[macro_export]
@@ -58,22 +66,33 @@ macro_rules! sel {
 Sends a message to an object.
 
 The first argument can be any type that dereferences to a type that implements
-`Message`, like a reference, pointer, or an `Id`.
+[`Message`], like a reference, a pointer, or an `objc_id::Id` to an object.
+
 The syntax is similar to the message syntax in Objective-C.
+
 Variadic arguments are not currently supported.
 
-# Example
+[`Message`]: crate::Message
+
+# Panics
+
+Panics if the `exception` feature is enabled and the Objective-C method throws
+an exception.
+
+And panics if the `verify_message` feature is enabled and the Objective-C
+method's argument's encoding does not match the encoding of the given arguments.
+
+# Examples
+
 ``` no_run
 # use objc::msg_send;
 # use objc::runtime::Object;
-# fn main() {
 # unsafe {
 let obj: *mut Object;
 # let obj: *mut Object = 0 as *mut Object;
 let description: *const Object = msg_send![obj, description];
 let _: () = msg_send![obj, setArg1:1 arg2:2];
 # }
-# }
 ```
 */
 #[macro_export]