doc(device-id): Define identifier characteristics

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

@@ -1,4 +1,6 @@
-//! General structure of a device identities.
+//! Tools and traits for describing device identities.
+//!
+//! See `riot_rs::identity` for general documentation.
 
 /// Describes how a board produces unique identifiers.
 pub trait DeviceId {

src/riot-rs/src/identity.rs

@@ -1,13 +1,33 @@
 //! Access to unique identifiers provided by the device.
+//!
+//! The main way to use this module is [`device_identity()`], which returns an identifier for the
+//! concrete piece of hardware that the software is running on.
+//!
+//! Concrete properties of a device identity are:
+//!
+//! * Identifiers are reasonably unique: They are either unique by construction (serial number, MAC
+//!   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.
+//!
+//! * 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.
+//!
+//! 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.
 
 #[doc(inline)]
 pub use riot_rs_embassy_common::identity::DeviceId;
 
 use crate::arch::identity::DeviceId as ArchDeviceId;
 
 /// Obtains a unique identifier of the device.
-///
-/// See also [`DeviceId`].
 pub fn device_identity(
 ) -> Result<<ArchDeviceId as DeviceId>::DeviceId, <ArchDeviceId as DeviceId>::Error> {
     riot_rs_embassy::arch::identity::DeviceId::get()