doc(device-id): Polish documentation

src/riot-rs-embassy-common/src/identity.rs

@@ -5,6 +5,8 @@
 
 /// Trait desribing the unique identifier available on a board.
 ///
+/// See the module level documentation on the characteristics of the identifier.
+///
 /// # Evolution
 ///
 /// In its current state, this type is mainly a wrapper around a binary identifier with a
@@ -17,7 +19,7 @@
 pub trait DeviceId: Sized + core::fmt::Debug + defmt::Format {
     /// Error type indicating that no identifier is available.
     ///
-    /// This is the return type of the [`::get()`][Self::get] constructor.
+    /// This is part of the return type of the [`::get()`][Self::get] constructor.
     ///
     /// It is encouraged to be [`core::convert::Infallible`] where possible.
     ///
@@ -29,6 +31,13 @@ pub trait DeviceId: Sized + core::fmt::Debug + defmt::Format {
 
     /// Some `[u8; N]` type, returned by [`.bytes()`][Self::bytes].
     ///
+    /// This may not represent all the identifying information available on the board, but can
+    /// represent a unique portion thereof.
+    ///
+    /// (For example, if a device has two consecutive MAC addresses assigned, the type as a whole
+    /// may represent both, but the conventional serialized identity of the board may just be one
+    /// of them).
+    ///
     /// # Evolution
     ///
     /// On the long run, it will be preferable to add a `const BYTES_LEN: usize;` and enforce the
@@ -38,33 +47,24 @@ pub trait DeviceId: Sized + core::fmt::Debug + defmt::Format {
 
     /// Obtains a unique identifier of the device.
     ///
-    /// For the type implementing this trait at its conventional position
-    /// `riot_rs::arch::identity::DeviceId`, a convenience function to call it exists at
-    /// `riot_rs::identity::device_identity()`.
-    ///
-    /// # Open questions
-    ///
-    /// Uniqueness is currently described in the scope of the board, but this is implemented as part of
-    /// the `arch`. Implementation experience will show what is more realistic.
-    ///
-    /// Ideally, those should be coordinated even outside of the project, so that a hypothetical
-    /// extension to probe-rs that connects to devices by their ID can reuse the identifiers. This will
-    /// require some more agreement on their structure as well as their scope. (probe-rs does not work
-    /// on boards but just on chips).
+    /// For callers, there is the convenience function `riot_rs::identity::device_identity()`
+    /// available, which just calls this trait method on `riot_rs::arch::identity::DeviceId`.
     ///
     /// # Errors
     ///
-    /// This prodcues an error if no device ID is available on this board, or is not implemented.
+    /// This produces an error if no device ID is available on this board, or is not implemented.
     fn get() -> Result<Self, Self::Error>;
 
     /// The device identifier in serialized bytes format.
     fn bytes(&self) -> Self::Bytes;
 }
 
-/// A type implementing [`DeviceId`] that always errs.
+/// An uninhabited type implementing [`DeviceId`] that always errs.
 ///
 /// This can be used both on architectures that do not have a unique identifier on their boards,
 /// and when it has not yet been implemented.
+///
+/// Typical types for `E` are [`NotImplemented`] or [`NotAvailable`].
 #[derive(Debug, defmt::Format)]
 pub struct NoDeviceId<E: core::error::Error + defmt::Format + Default>(
     core::convert::Infallible,

src/riot-rs/src/identity.rs

@@ -9,15 +9,15 @@
 //!   address) or random identifiers (>= 64 bit).
 //!
 //! * The scope of the identifier is within a RIOT-rs board. Their scope may be broader, eg. when
-//!   a identifier is unique per MCU family, or evenglobally.
+//!   a identifier is unique per MCU family, or even globally.
 //!
 //! * Identifiers do not change during regular development with a board, which includes the use of
 //!   programmer. Identifiers may change under deliberate conditions, eg. when a device has a
 //!   one-time programmable identity, or when there is a custom functionality to overwrite the
 //!   built-in identifier that is not triggered by the device erase that is performed as part of
 //!   programming the device.
 //!
-//! If a board has no means of providing such an identifier, an error is returned.
+//! Constructing an identifier fails rather than producing a dummy identifier.
 //!
 //! It is considered a breaking change in a board or this module if a board's identifier changes or
 //! becomes an error as result of an update to RIOT-rs; errors may change to valid identifiers.