can: try_ prefixes and improved documentation

Author: timokroeger

src/can.rs

@@ -68,13 +68,21 @@ pub trait Can {
     /// Associated error type.
     type Error;
 
-    /// Puts a frame in the transmit buffer.
+    /// Puts a frame in the transmit buffer to be sent on the bus.
     ///
-    /// If the buffer is full, this function will try to replace a lower priority frame
-    /// and return it. This is to avoid the priority inversion problem.
-    /// Transmits frames of equal identifier in FIFO fashion.
-    fn transmit(&mut self, frame: &Self::Frame) -> nb::Result<Option<Self::Frame>, Self::Error>;
+    /// If the transmit buffer is full, this function will try to replace a pending
+    /// lower priority frame and return the frame that was replaced.
+    /// Returns `Err(WouldBlock)` if the transmit buffer is full and no frame can be
+    /// replaced.
+    ///
+    /// # Notes for implementers
+    ///
+    /// * Frames of equal identifier shall be transmited in FIFO fashion when more
+    ///   than one transmit buffer is available.
+    /// * When replacing pending frames make sure the frame is not in the process of
+    ///   being send to the bus.
+    fn try_transmit(&mut self, frame: &Self::Frame) -> nb::Result<Option<Self::Frame>, Self::Error>;
 
     /// Returns a received frame if available.
-    fn receive(&mut self) -> nb::Result<Self::Frame, Self::Error>;
+    fn try_receive(&mut self) -> nb::Result<Self::Frame, Self::Error>;
 }