Improve docs.

src/rights.rs

@@ -1,4 +1,15 @@
 //! Provides wrappers for Mach port right names.
+//!
+//! The module provides 3 types [`SendRight`], [`SendOnceRight`] and [`RecvRight`] that are wrappers
+//! for raw `mach_port_t` values (aka Mach port names).
+//!
+//! # Ownership
+//!
+//! Each of these values represent a single user reference on the corresponding right to a Mach
+//! port. That means when a value is dropped, the task loses a reference to the Mach port right
+//! represented by the wrapped name (through a call to `mach_port_mod_refs`). Additionally,
+//! [`SendRight`] wrappers can be cloned which increases the number of references to the port's
+//! send right.
 
 use crate::{
     msg::{MsgBuffer, MsgBuilder, MsgParser, RecvError, SendError},
@@ -98,14 +109,14 @@ impl SendRight {
 impl Clone for SendRight {
     #[inline(always)]
     fn clone(&self) -> Self {
-        self.mod_refs(1);
+        assert_eq!(self.mod_refs(1), KERN_SUCCESS);
 
         SendRight(self.0)
     }
 
     #[inline(always)]
     fn clone_from(&mut self, source: &Self) {
-        source.mod_refs(1);
+        assert_eq!(self.mod_refs(1), KERN_SUCCESS);
 
         self.0 = source.0;
     }

src/traits.rs

@@ -2,24 +2,33 @@
 
 use mach2::port::{mach_port_right_t, mach_port_t};
 
-/// A trait for everything that wraps a raw Mach port name (aka `mach_port_t`) and can be converted
-/// into it.
+/// A trait to get a raw Mach port name (`mach_port_t`) from an object.
 pub trait AsRawName {
     /// Specifies the disposition value to be set in a port descriptor when the represented right
     /// reference has to be moved to the receiver's IPC space.
     ///
     /// This should be one of the `MACH_MSG_TYPE_MOVE_*` constants.
     const MSG_TYPE: mach_port_right_t;
 
-    /// Converts a type into a raw Mach port name. This function should not alter reference counts
-    /// of any port rights.
+    /// Extracts the raw Mach port name.
+    ///
+    /// This function is intended to **borrow** a Mach port right reference. That is, the ownership
+    /// of the reference isn't passed to the caller, and the name is only guaranteed to represent
+    /// the corresponding port right only during the lifetime of the original object.
+    ///
+    /// This function should not alter reference counts of the port right represented by the name.
     fn as_raw_name(&self) -> mach_port_t;
 }
 
-/// A trait for everything that wraps a raw Mach port name (aka `mach_port_t`) and can be converted
-/// into it.
+/// A trait to convert an object into a raw Mach port name (`mach_port_t`) while taking ownership
+/// of the port right reference represented by the name.
 pub trait IntoRawName: AsRawName {
-    /// Converts a type into a raw Mach port name. This function should not alter reference counts
-    /// of any port rights.
+    /// Converts an object into a raw Mach port name.
+    ///
+    /// This function is intended to **pass** a Mach port right reference from a destructed object
+    /// to the caller. That means the caller will be responsible for properly dropping the reference
+    /// when it is no longer needed.
+    ///
+    /// This function should not alter reference counts of the port right represented by the name.
     fn into_raw_name(self) -> mach_port_t;
 }