Rust API: Add rustdoc examples to moteus-protocol public items

Add examples to key entry points: calculate/parse_arbitration_id,
PositionCommand, StayWithinCommand, CurrentCommand, QueryFormat,
QueryResult::parse, parse_frame, Value::to_f32, Mode::is_error.
Cross-reference lesser-used types to the primary examples.

Author: jpieper

lib/rust/moteus-protocol/src/command.rs

@@ -75,6 +75,25 @@ impl Default for PositionFormat {
 ///
 /// This is the primary control mode for moteus. All fields are optional;
 /// fields set to `None` will not be transmitted (using Ignore resolution).
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::CanFdFrame;
+/// use moteus_protocol::command::{PositionCommand, PositionFormat};
+///
+/// let mut frame = CanFdFrame::new();
+/// frame.arbitration_id = 0x8001;
+///
+/// // Build with the builder pattern -- fields are optional
+/// let cmd = PositionCommand::new()
+///     .position(0.5)
+///     .velocity(1.0)
+///     .maximum_torque(2.0);
+///
+/// cmd.serialize(&mut frame, &PositionFormat::default());
+/// assert!(frame.size > 0);
+/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Default, Setters)]
 pub struct PositionCommand {
@@ -286,6 +305,8 @@ impl Default for VFOCFormat {
 }
 
 /// Voltage-mode FOC command.
+///
+/// See [`PositionCommand`] for an example of building and serializing commands.
 #[non_exhaustive]
 #[derive(Debug, Clone, Setters)]
 pub struct VFOCCommand {
@@ -378,6 +399,19 @@ impl Default for CurrentFormat {
 }
 
 /// DQ-axis current command.
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::CanFdFrame;
+/// use moteus_protocol::command::{CurrentCommand, CurrentFormat};
+///
+/// let mut frame = CanFdFrame::new();
+/// let cmd = CurrentCommand::new()
+///     .d_current(0.0)
+///     .q_current(0.5);
+/// cmd.serialize(&mut frame, &CurrentFormat::default());
+/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone)]
 pub struct CurrentCommand {
@@ -469,6 +503,22 @@ impl Default for StayWithinFormat {
 }
 
 /// Stay-within mode command.
+///
+/// Unlike [`PositionCommand`] which drives to a target, this mode keeps the
+/// servo within position bounds while applying minimal control effort.
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::CanFdFrame;
+/// use moteus_protocol::command::{StayWithinCommand, StayWithinFormat};
+///
+/// let mut frame = CanFdFrame::new();
+/// let cmd = StayWithinCommand::new()
+///     .lower_bound(-0.5)
+///     .upper_bound(0.5);
+/// cmd.serialize(&mut frame, &StayWithinFormat::default());
+/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Default, Setters)]
 pub struct StayWithinCommand {
@@ -616,6 +666,8 @@ impl Default for ZeroVelocityFormat {
 }
 
 /// Zero-velocity mode command.
+///
+/// See [`PositionCommand`] for an example of building and serializing commands.
 #[non_exhaustive]
 #[derive(Debug, Clone, Default, Setters)]
 pub struct ZeroVelocityCommand {

lib/rust/moteus-protocol/src/frame.rs

@@ -182,6 +182,22 @@ impl core::fmt::Debug for CanFdFrame {
 /// - bit 15     = reply expected flag
 /// - bits 14:8  = source (7 bits)
 /// - bits 7:0   = destination (8 bits)
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::{calculate_arbitration_id, parse_arbitration_id};
+///
+/// // Build an arbitration ID for source=0, dest=1, no prefix, reply expected
+/// let arb_id = calculate_arbitration_id(0, 1, 0, true);
+/// assert_eq!(arb_id, 0x8001);
+///
+/// // Parse it back
+/// let (source, dest, prefix) = parse_arbitration_id(arb_id);
+/// assert_eq!(source, 0);
+/// assert_eq!(dest, 1);
+/// assert_eq!(prefix, 0);
+/// ```
 pub fn calculate_arbitration_id(
     source: i8,
     destination: i8,
@@ -199,6 +215,17 @@ pub fn calculate_arbitration_id(
 ///
 /// Returns (source, destination, can_prefix).
 /// This is the inverse of [`calculate_arbitration_id`].
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::parse_arbitration_id;
+///
+/// // Extract routing from a received frame's arbitration ID
+/// let (source, dest, prefix) = parse_arbitration_id(0x8100);
+/// assert_eq!(source, 1);  // device 1 sent this
+/// assert_eq!(dest, 0);    // addressed to us
+/// ```
 pub fn parse_arbitration_id(arb_id: u32) -> (i8, i8, u16) {
     let source = ((arb_id >> 8) & 0x7F) as i8;
     let destination = (arb_id & 0xFF) as i8;

lib/rust/moteus-protocol/src/mode.rs

@@ -83,6 +83,20 @@ impl core::fmt::Display for Mode {
 
 impl Mode {
     /// Returns `true` if the controller is in an error state.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use moteus_protocol::Mode;
+    ///
+    /// let mode = Mode::Position;
+    /// assert!(mode.is_active());
+    /// assert!(!mode.is_error());
+    ///
+    /// let fault = Mode::Fault;
+    /// assert!(fault.is_error());
+    /// assert!(!fault.is_active());
+    /// ```
     pub fn is_error(&self) -> bool {
         matches!(self, Mode::Fault | Mode::Timeout)
     }

lib/rust/moteus-protocol/src/multiplex.rs

@@ -394,6 +394,17 @@ impl Value {
     /// Integer minimum values (e.g., -128 for Int8) are mapped to NaN.
     /// Integer values are multiplied by the appropriate scaling factor.
     /// Float values are returned directly.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use moteus_protocol::multiplex::Value;
+    /// use moteus_protocol::scaling;
+    ///
+    /// let raw = Value::Int16(5000);
+    /// let position = raw.to_f32(&scaling::POSITION);
+    /// assert!((position - 0.5).abs() < 0.001); // 5000 * 0.0001 = 0.5 rev
+    /// ```
     pub fn to_f32(&self, scaling: &Scaling) -> f32 {
         use crate::scaling::{nanify_i16, nanify_i32, nanify_i8};
 
@@ -467,6 +478,8 @@ pub enum Subframe<'a> {
 ///
 /// Handles all opcode families: WRITE (0x00-0x0f), READ (0x10-0x1f),
 /// REPLY (0x20-0x2f), ERROR (0x30-0x31), STREAM (0x40-0x42), NOP (0x50).
+///
+/// See [`parse_frame`] for a convenience wrapper.
 pub struct FrameParser<'a> {
     data: &'a [u8],
     offset: usize,
@@ -786,6 +799,23 @@ impl<'a> Iterator for FrameParser<'a> {
 }
 
 /// Creates a parser that iterates over all subframes in a multiplex protocol frame.
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::multiplex::{parse_frame, Subframe};
+///
+/// // A response frame with mode=10 (position) at register 0
+/// let data = [0x21, 0x00, 0x0a];
+/// for subframe in parse_frame(&data) {
+///     match subframe {
+///         Subframe::Register { register, value, .. } => {
+///             println!("Register 0x{:03x} = {:?}", register, value);
+///         }
+///         _ => {}
+///     }
+/// }
+/// ```
 pub fn parse_frame(data: &[u8]) -> FrameParser<'_> {
     FrameParser::new(data)
 }

lib/rust/moteus-protocol/src/query.rs

@@ -30,6 +30,24 @@ pub const MAX_EXTRA: usize = 16;
 ///
 /// Specifies which registers to query and at what resolution.
 /// Setting a field to `Resolution::Ignore` means that register will not be queried.
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::Resolution;
+/// use moteus_protocol::query::QueryFormat;
+///
+/// // Default format queries position, velocity, torque, and q_current
+/// let default = QueryFormat::default();
+///
+/// // Comprehensive format includes all standard registers
+/// let full = QueryFormat::comprehensive();
+///
+/// // Or customize individual registers
+/// let mut custom = QueryFormat::default();
+/// custom.abs_position = Resolution::Float;
+/// custom.voltage = Resolution::Int16;
+/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone)]
 pub struct QueryFormat {
@@ -267,6 +285,21 @@ pub struct ExtraValue {
 }
 
 /// Result of parsing a query response.
+///
+/// # Examples
+///
+/// ```
+/// use moteus_protocol::CanFdFrame;
+/// use moteus_protocol::query::QueryResult;
+///
+/// // After receiving a response frame from the device...
+/// fn handle_response(frame: &CanFdFrame) {
+///     let result = QueryResult::parse(frame);
+///     if result.mode.is_error() {
+///         eprintln!("Fault code: {}", result.fault);
+///     }
+/// }
+/// ```
 #[non_exhaustive]
 #[derive(Debug, Clone, Default)]
 pub struct QueryResult {