DOCS-2591: Add motor and servo example snippets (#240)

* DOCS-2591: Add motor and servo example snippets

* remove extra space

lib/src/components/gripper/gripper.dart

@@ -6,7 +6,7 @@ import '../../robot/client.dart';
 abstract class Gripper extends Resource {
   static const Subtype subtype = Subtype(resourceNamespaceRDK, resourceTypeComponent, 'gripper');
 
-  /// Open the [Gripper]
+  /// Open the [Gripper].
   ///
   /// ```
   /// await myGripper.open();
@@ -20,14 +20,14 @@ abstract class Gripper extends Resource {
   /// ```
   Future<void> grab({Map<String, dynamic>? extra});
 
-  /// Stop all motion of the [Gripper]. It is assumed the [Gripper] stops immediately
+  /// Stop all motion of the [Gripper]. It is assumed the [Gripper] stops immediately.
   ///
   /// ```
   /// await myGripper.stop();
   /// ```
   Future<void> stop({Map<String, dynamic>? extra});
 
-  /// If the [Gripper] is currently moving
+  /// Whether the [Gripper] is currently moving.
   ///
   /// ```
   /// var isItMoving = await myGripper.isMoving();

lib/src/components/motor/motor.dart

@@ -22,45 +22,105 @@ abstract class Motor extends Resource {
 
   /// Sets the "percentage" of power the [Motor] should employ between -1 and 1.
   /// When [powerPct] is negative, the rotation will be in the backward direction.
+  ///
+  /// ```
+  /// // Set the power to  40% forwards.
+  /// await myMotor.setPower(0.4);
+  /// ```
   Future<void> setPower(double powerPct, {Map<String, dynamic>? extra});
 
   /// Spin the [Motor] the specified number of [revolutions] at specified [rpm].
   /// When [rpm] or [revolutions] is a negative value, the rotation will be in the backward direction.
   /// Note: if both [rpm] and [revolutions] are negative, the motor will spin in the forward direction.
+  ///
+  /// ```
+  /// // Turn the motor 7.2 revolutions forward at 60 RPM.
+  /// await myMotor.goFor(60, 7.2);
+  /// ```
   Future<void> goFor(double rpm, double revolutions, {Map<String, dynamic>? extra});
 
   /// Spin the [Motor] to the specified position (provided in revolutions from home/zero),
   /// at the specified speed, in revolutions per minute.
   /// Regardless of the directionality of the [rpm] this function will move
   /// the [Motor] towards the specified position.
+  ///
+  /// ```
+  /// // Turn the motor to 8.3 revolutions from home at 75 RPM.
+  /// await myMotor.goTo(75, 8.3);
+  /// ```
   Future<void> goTo(double rpm, double positionRevolutions, {Map<String, dynamic>? extra});
 
   /// Spin the [Motor] indefinitely at the specified speed, in revolutions per minute.
   /// If [rpm] is positive, the motor will spin forwards, and if [rpm] is negative, the motor will spin backwards.
+  ///
+  /// ```
+  /// // Set the motor to turn backwards at 120.5 RPM.
+  /// await myMotor.setRPM(-120.5);
+  /// ```
   Future<void> setRPM(double rpm, {Map<String, dynamic>? extra});
 
   /// Set the current position (modified by [offset]) to be the new zero (home) position.
+  ///
+  /// ```
+  /// // Set the current position as the new home position with no offset.
+  /// await myMotor.resetZeroPosition(0.0);
+  /// ```
   Future<void> resetZeroPosition(double offset, {Map<String, dynamic>? extra});
 
   /// Report the position of the motor based on its encoder.
   /// The value returned is the number of revolutions relative to its zero position.
   /// This method will raise an exception if position reporting is not supported by the motor.
+  ///
+  /// ```
+  /// // Get the current position of an encoded motor.
+  /// var position = await myMotor.position();
+  /// ```
   Future<double> position({Map<String, dynamic>? extra});
 
-  /// Report a dictionary mapping optional properties to
+  /// Report a dictionary mapping each optional property to
   /// whether it is supported by this motor.
+  ///
+  /// ```
+  /// // Return whether the motor supports certain optional features
+  /// var properties = await myMotor.properties();
+  /// ```
   Future<MotorProperties> properties({Map<String, dynamic>? extra});
 
   /// Stop the motor immediately, without any gradual step down.
+  ///
+  /// ```
+  /// // Stop the motor.
+  /// await myMotor.stop();
+  /// ```
   Future<void> stop({Map<String, dynamic>? extra});
 
-  /// Returns whether or not the motor is currently running.
+  /// Returns whether or not the motor is currently powered, and the portion
+  /// of max power (between 0 and 1; 0 indicates that power is off). Stepper
+  /// motors report `true` if they are being powered while holding a position,
+  /// as well as when they are turning themselves.
+  ///
+  /// ```
+  /// // Check whether the motor is currently powered and
+  /// // check the percentage of max power to the motor.
+  /// var powerState = await myMotor.powerState();
+  /// var powered = powerState.isOn;
+  /// var pct = powerState.powerPct;
+  /// ```
   Future<PowerState> powerState({Map<String, dynamic>? extra});
 
   /// Get if the [Motor] is currently moving.
+  ///
+  /// ```
+  /// // Check whether the motor is moving.
+  /// var moving = await myMotor.isMoving();
+  /// ```
   Future<bool> isMoving({Map<String, dynamic>? extra});
 
-  /// Get the [ResourceName] for this [Motor] with the given [name]
+  /// Get the [ResourceName] for this [Motor] with the given [name].
+  ///
+  /// ```
+  /// var name = Motor.getResourceName('myMotor');
+  /// ```
   static ResourceName getResourceName(String name) {
     return Motor.subtype.getResourceName(name);
   }

lib/src/components/power_sensor/power_sensor.dart

@@ -23,19 +23,19 @@ abstract class PowerSensor extends Resource {
   /// AC (true) or DC (false).
   ///
   /// ```
-  /// var voltageObject = await myPowerSensor.readings();
-  /// double voltageInVolts = voltageObject['volts'];
-  /// bool isItAC = voltageObject['isAc'];
+  /// var voltageObject = await myPowerSensor.voltage();
+  /// double voltageInVolts = voltageObject.volts;
+  /// bool isItAC = voltageObject.isAc;
   /// ```
   Future<Voltage> voltage({Map<String, dynamic>? extra});
 
   /// Get the current in amperes, and whether the current
   /// is AC (true) or DC (false).
   ///
   /// ```
-  /// var currentObject = await myPowerSensor.readings();
-  /// double amps = voltageObject['amperes'];
-  /// bool isItAC = voltageObject['isAc'];
+  /// var currentObject = await myPowerSensor.current();
+  /// double amps = currentObject.amperes;
+  /// bool isItAC = currentObject.isAc;
   /// ```
   Future<Current> current({Map<String, dynamic>? extra});
 

lib/src/components/servo/servo.dart

@@ -10,15 +10,31 @@ abstract class Servo extends Resource {
   Future<void> move(int angle, {Map<String, dynamic>? extra});
 
   /// Get the current angle (degrees) of the [Servo].
+  ///
+  /// ```
+  /// var angle = await myServo.position();
+  /// ```
   Future<int> position({Map<String, dynamic>? extra});
 
   /// Stop the [Servo]. It is assumed that the servo stops immediately.
+  ///
+  /// ```
+  /// await myServo.stop();
+  /// ```
   Future<void> stop({Map<String, dynamic>? extra});
 
-  /// Get if the [Servo] is currently moving.
+  /// Whether the [Servo] is currently moving.
+  /// ```
+  /// var isItMoving = await myServo.isMoving();
+  /// ```
   Future<bool> isMoving();
 
-  /// Get the [ResourceName] for this [Servo] with the given [name]
+  /// Get the [ResourceName] for this [Servo] with the given [name].
+  ///
+  /// ```
+  /// // Example:
+  /// var name = Servo.getResourceName('myServo');
+  /// ```
   static ResourceName getResourceName(String name) {
     return Servo.subtype.getResourceName(name);
   }