Somewhat document extern_protocol!

crates/objc2/src/macros/extern_protocol.rs

@@ -1,4 +1,36 @@
-/// TODO
+/// Create a new type to represent an Objective-C protocol.
+///
+/// This is similar to a `@protocol` declaration in Objective-C.
+///
+/// This macro shares many similarities with [`extern_class!`] and
+/// [`extern_methods!`], if you are familiar with those, it should be fairly
+/// straightforward to use.
+///
+/// It differs in a few aspects though:
+/// - You can use the `#[optional]` attribute to mark optional methods. This
+///   currently doesn't have any effect, but will probably in the future.
+/// - Class methods are not (yet) supported.
+/// - Protocols do not have a direct parent/child relationship, so specifying
+///   a parent is not required. However, to make usage easier if the protocol
+///   only directly conforms to one protocol, you may specify a "parent"
+///   protocol that this protocol will `Deref` to.
+/// - Other protocols that this protocol conforms to can be specified using
+///   the `#[conforms_to(...)]` attribute, similar to `#[inherits(...)]` in
+///   [`extern_class!`].
+///
+/// [`extern_class!`]: crate::extern_class
+/// [`extern_methods!`]: crate::extern_methods
+/// [`ConformsTo`]: crate::ConformsTo
+///
+///
+/// # Safety
+///
+/// - The specified name must be an exisiting Objective-C protocol.
+/// - The protocol must actually inherit/conform to the protocols specified in
+///   `#[conforms_to(...)]`.
+/// - If a parent protocol is specified, the protocol must inherit/conform to
+///   said protocol.
+/// - The protocol's methods must be correctly specified.
 #[doc(alias = "@protocol")]
 #[macro_export]
 macro_rules! extern_protocol {
@@ -150,13 +182,16 @@ macro_rules! __extern_protocol_inner {
             }
         );
 
-        // SAFETY: TODO
+        // SAFETY: The specified name is ensured by caller to be a protocol,
+        // and is correctly defined.
         unsafe impl ProtocolType for $for {
             const NAME: &'static str = $name_const;
             const __INNER: () = ();
         }
 
         $(
+            // SAFETY: Caller ensures that the protocol actually conforms to
+            // these protocols.
             unsafe impl $crate::ConformsTo<$conforms_to> for $for {}
         )*
 

crates/objc2/src/protocol.rs

@@ -34,7 +34,7 @@ use crate::Message;
 ///
 /// Use the [`extern_protocol!`] macro to implement this trait for a type.
 ///
-/// ```ignore
+/// ```no_run
 /// use objc2::{extern_protocol, ProtocolType};
 ///
 /// extern_protocol!(