Rearrange errors and clarify their semantics.

src/lib.rs

@@ -97,33 +97,37 @@ pub mod iface;
 pub mod socket;
 
 /// The error type for the networking stack.
-#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub enum Error {
-    /// An incoming packet could not be parsed.
+    /// An operation cannot proceed because a buffer is empty or full.
+    Exhausted,
+    /// An endpoint or address of a remote host could not be translated to a lower level address.
+    /// E.g. there was no an Ethernet address corresponding to an IPv4 address in the ARP cache,
+    /// or a TCP connection attempt was made to an unspecified endpoint.
+    Unaddressable,
+
+    /// An incoming packet could not be parsed because some of its fields were out of bounds
+    /// of the received data.
     Truncated,
-    /// An incoming packet could not be recognized and was dropped.
-    /// E.g. a packet with an unknown EtherType.
-    Unrecognized,
-    /// An incoming packet was recognized but contained invalid control information.
-    /// E.g. a packet with IPv4 EtherType but containing a value other than 4
-    /// in the version field.
-    Malformed,
     /// An incoming packet had an incorrect checksum and was dropped.
     Checksum,
-    /// An incoming packet has been fragmented and was dropped.
+    /// An incoming packet could not be recognized and was dropped.
+    /// E.g. an Ethernet packet with an unknown EtherType.
+    Unrecognized,
+    /// An incoming IP packet has been split into several IP fragments and was dropped,
+    /// since IP reassembly is not supported.
     Fragmented,
-    /// An outgoing packet could not be sent because a protocol address could not be mapped
-    /// to hardware address. E.g. an IPv4 packet did not have an Ethernet address
-    /// corresponding to its IPv4 destination address.
-    Unaddressable,
-    /// A buffer for incoming packets is empty, or a buffer for outgoing packets is full.
-    Exhausted,
-    /// An incoming packet does not match the socket endpoint.
-    Rejected,
-    /// An incoming packet was recognized by a stateful socket and contained invalid control
-    /// information that caused the socket to drop it.
+    /// An incoming packet was recognized but was self-contradictory.
+    /// E.g. a TCP packet with both SYN and FIN flags set.
+    Malformed,
+    /// An incoming packet was recognized but contradicted internal state.
+    /// E.g. a TCP packet addressed to a socket that doesn't exist.
     Dropped,
 
+    // Implementation detail.
+    #[doc(hidden)]
+    Rejected,
+
     #[doc(hidden)]
     __Nonexhaustive
 }
@@ -131,15 +135,15 @@ pub enum Error {
 impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         match self {
+            &Error::Exhausted     => write!(f, "buffer space exhausted"),
+            &Error::Unaddressable => write!(f, "unaddressable destination"),
             &Error::Truncated     => write!(f, "truncated packet"),
-            &Error::Unrecognized  => write!(f, "unrecognized packet"),
-            &Error::Malformed     => write!(f, "malformed packet"),
             &Error::Checksum      => write!(f, "checksum error"),
+            &Error::Unrecognized  => write!(f, "unrecognized packet"),
             &Error::Fragmented    => write!(f, "fragmented packet"),
-            &Error::Unaddressable => write!(f, "unaddressable destination"),
-            &Error::Exhausted     => write!(f, "buffer space exhausted"),
-            &Error::Rejected      => write!(f, "rejected by socket"),
+            &Error::Malformed     => write!(f, "malformed packet"),
             &Error::Dropped       => write!(f, "dropped by socket"),
+            &Error::Rejected      => write!(f, "rejected by socket"),
             &Error::__Nonexhaustive => unreachable!()
         }
     }