tock-register-interface: improve read_as_enum documentation

The tock-register-interface's README contained an incorrect usage
example of the `Readable::read_as_enum` method. Because of its
non-trivial type signature, using the custom TryFromValue trait, this
adds extensive documentation and doctests outlining the relationship
with the generated structures and enums through `register_bitfields!`.

Suggested-by: nihalpasham <nihal.pasham@gmail.com>
Signed-off-by: Leon Schuermann <leon@is.currently.online>

Author: lschuermann

libraries/tock-register-interface/README.md

@@ -356,8 +356,8 @@ let any_ints = registers.s.matches_any(Status::TXINTERRUPT + Status::RXINTERRUPT
 let mode = registers.cr.read_as_enum(Status::MODE);
 
 match mode {
-    Some(Status::MODE::FullDuplex) => { /* ... */ }
-    Some(Status::MODE::HalfDuplex) => { /* ... */ }
+    Some(Status::MODE::Value::FullDuplex) => { /* ... */ }
+    Some(Status::MODE::Value::HalfDuplex) => { /* ... */ }
 
     None => unreachable!("invalid value")
 }

libraries/tock-register-interface/src/fields.rs

@@ -101,6 +101,42 @@ impl<T: UIntLike, R: RegisterLongName> Field<T, R> {
 
     #[inline]
     /// Read value of the field as an enum member
+    ///
+    /// This method expects to be passed the unasked and unshifted register
+    /// value, extracts the field value by calling [`Field::read`] and
+    /// subsequently passes that value to the [`TryFromValue`] implementation on
+    /// the passed enum type.
+    ///
+    /// The [`register_bitfields!`](crate::register_bitfields) macro will
+    /// generate an enum containing the various named field variants and
+    /// implementing the required [`TryFromValue`] trait. It is accessible as
+    /// `$REGISTER_NAME::$FIELD_NAME::Value`.
+    ///
+    /// This method can be useful to symbolically represent read register field
+    /// states throughout the codebase and to enforce exhaustive matches over
+    /// all defined valid register field values.
+    ///
+    /// ## Usage Example
+    ///
+    /// ```rust
+    /// # use tock_registers::interfaces::Readable;
+    /// # use tock_registers::registers::InMemoryRegister;
+    /// # use tock_registers::register_bitfields;
+    /// register_bitfields![u8,
+    ///     EXAMPLEREG [
+    ///         TESTFIELD OFFSET(3) NUMBITS(3) [
+    ///             Foo = 2,
+    ///             Bar = 3,
+    ///             Baz = 6,
+    ///         ],
+    ///     ],
+    /// ];
+    ///
+    /// match EXAMPLEREG::TESTFIELD.read_as_enum(0x9C) {
+    ///     Some(EXAMPLEREG::TESTFIELD::Value::Bar) => "The value is 3!",
+    ///     _ => panic!("boo!"),
+    /// };
+    /// ```
     pub fn read_as_enum<E: TryFromValue<T, EnumType = E>>(self, val: T) -> Option<E> {
         E::try_from_value(self.read(val))
     }

libraries/tock-register-interface/src/interfaces.rs

@@ -173,8 +173,44 @@ pub trait Readable {
         field.read(self.get())
     }
 
-    #[inline]
     /// Set the raw register value
+    ///
+    /// The [`register_bitfields!`](crate::register_bitfields) macro will
+    /// generate an enum containing the various named field variants and
+    /// implementing the required [`TryFromValue`] trait. It is accessible as
+    /// `$REGISTER_NAME::$FIELD_NAME::Value`.
+    ///
+    /// This method can be useful to symbolically represent read register field
+    /// states throughout the codebase and to enforce exhaustive matches over
+    /// all defined valid register field values.
+    ///
+    /// ## Usage Example
+    ///
+    /// ```rust
+    /// # use tock_registers::interfaces::Readable;
+    /// # use tock_registers::registers::InMemoryRegister;
+    /// # use tock_registers::register_bitfields;
+    /// register_bitfields![u8,
+    ///     EXAMPLEREG [
+    ///         TESTFIELD OFFSET(0) NUMBITS(2) [
+    ///             Foo = 0,
+    ///             Bar = 1,
+    ///             Baz = 2,
+    ///         ],
+    ///     ],
+    /// ];
+    ///
+    /// let reg: InMemoryRegister<u8, EXAMPLEREG::Register> =
+    ///     InMemoryRegister::new(2);
+    ///
+    /// match reg.read_as_enum(EXAMPLEREG::TESTFIELD) {
+    ///     Some(EXAMPLEREG::TESTFIELD::Value::Foo) => "Tock",
+    ///     Some(EXAMPLEREG::TESTFIELD::Value::Bar) => "is",
+    ///     Some(EXAMPLEREG::TESTFIELD::Value::Baz) => "awesome!",
+    ///     None => panic!("boo!"),
+    /// };
+    /// ```
+    #[inline]
     fn read_as_enum<E: TryFromValue<Self::T, EnumType = E>>(
         &self,
         field: Field<Self::T, Self::R>,