serialize: add doc comment and refactor Flags (#889)

serialize/src/flags.rs

@@ -12,30 +12,29 @@ pub trait Flags: Default + Clone + Copy + Sized {
     /// This should be at most 8.
     const BIT_SIZE: usize;
 
-    // Returns a bit mask corresponding to `self`.
-    // For example, if `Self` contains two variants, there are just two possible
-    // bit masks: `0` and `1 << 7`.
+    /// Returns a bit mask corresponding to `self`.
+    /// For example, if `Self` contains two variants, there are just two possible
+    /// bit masks: `0` and `1 << 7`.
     fn u8_bitmask(&self) -> u8;
 
-    // Tries to read `Self` from `value`. Should return `None` if the
-    // `Self::BIT_SIZE` most-significant bits of `value` do not correspond to
-    // those generated by `u8_bitmask`.
-    //
-    // That is, this method ignores all but the top `Self::BIT_SIZE` bits, and
-    // decides whether these top bits correspond to a bitmask output by
-    // `u8_bitmask`.
+    /// Tries to read `Self` from `value`. Should return `None` if the
+    /// `Self::BIT_SIZE` most-significant bits of `value` do not correspond to
+    /// those generated by `u8_bitmask`.
+    ///
+    /// That is, this method ignores all but the top `Self::BIT_SIZE` bits, and
+    /// decides whether these top bits correspond to a bitmask output by
+    /// `u8_bitmask`.
     fn from_u8(value: u8) -> Option<Self>;
 
-    // Convenience method that reads `Self` from `value`, just like `Self::from_u8`,
-    // but additionally zeroes out the bits corresponding to the resulting flag
-    // in `value`. If `Self::from_u8(*value)` would return `None`, then this
-    // method should *not* modify `value`.
+    /// Convenience method that reads `Self` from `value`, just like `Self::from_u8`,
+    /// but additionally zeroes out the bits corresponding to the resulting flag
+    /// in `value`. If `Self::from_u8(*value)` would return `None`, then this
+    /// method should *not* modify `value`.
     fn from_u8_remove_flags(value: &mut u8) -> Option<Self> {
-        let flags = Self::from_u8(*value);
-        if let Some(f) = flags {
+        Self::from_u8(*value).map(|f| {
             *value &= !f.u8_bitmask();
-        }
-        flags
+            f
+        })
     }
 }