DOCS-3541: Add sensor code samples

src/components/movement-sensor/movement-sensor.ts

@@ -18,36 +18,140 @@ export const {
  * position, and/or speed.
  */
 export interface MovementSensor extends Resource {
-  /** Get linear velocity across x/y/z axes */
+  /**
+   * Get linear velocity across x/y/z axes.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const linearVelocity = await movementSensor.getLinearVelocity();
+   * ```
+   */
   getLinearVelocity(extra?: Struct): Promise<Vector3>;
 
-  /** Get the angular velocity across x/y/z axes */
+  /**
+   * Get the angular velocity across x/y/z axes.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const angularVelocity = await movementSensor.getAngularVelocity();
+   * ```
+   */
   getAngularVelocity(extra?: Struct): Promise<Vector3>;
 
   /**
    * Get the compass heading, which is a number from 0-359 where 0 is North, 90
-   * is East, 180 is South, and 270 is West
+   * is East, 180 is South, and 270 is West.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const compassHeading = await movementSensor.getCompassHeading();
+   * ```
    */
   getCompassHeading(extra?: Struct): Promise<number>;
 
   /**
-   * Get the compass heading, which is a number from 0-359 where 0 is North, 90
-   * is East, 180 is South, and 270 is West
+   * Get the current orientation of the sensor.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const orientation = await movementSensor.getOrientation();
+   * ```
    */
   getOrientation(extra?: Struct): Promise<Orientation>;
 
-  /** Get the current position latitude, longitude, and altitude */
+  /**
+   * Get the current position latitude, longitude, and altitude.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const position = await movementSensor.getPosition();
+   * ```
+   */
   getPosition(extra?: Struct): Promise<MovementSensorPosition>;
 
-  /** Get the properties of this movement sensor */
+  /**
+   * Get the properties of this movement sensor.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const properties = await movementSensor.getProperties();
+   * ```
+   */
   getProperties(extra?: Struct): Promise<MovementSensorProperties>;
 
-  /** Get the accuracy of various sensors */
+  /**
+   * Get the accuracy of various sensors.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const accuracy = await movementSensor.getAccuracy();
+   * ```
+   */
   getAccuracy(extra?: Struct): Promise<MovementSensorAccuracy>;
 
-  /** Get linear acceleration across x/y/z axes */
+  /**
+   * Get linear acceleration across x/y/z axes.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const linearAcceleration =
+   *   await movementSensor.getLinearAcceleration();
+   * ```
+   */
   getLinearAcceleration(extra?: Struct): Promise<Vector3>;
 
-  /** Return the readings of a sensor. */
+  /**
+   * Return the readings of a sensor.
+   *
+   * @example
+   *
+   * ```ts
+   * const movementSensor = new VIAM.MovementSensorClient(
+   *   machine,
+   *   'my_movement_sensor'
+   * );
+   * const readings = await movementSensor.getReadings();
+   * ```
+   */
   getReadings(extra?: Struct): Promise<Record<string, JsonValue>>;
 }

src/components/power-sensor/power-sensor.ts

@@ -3,12 +3,62 @@ import type { Sensor } from '../sensor';
 
 /** Represents any sensor that reports voltage, current, and/or power */
 export interface PowerSensor extends Sensor {
-  /** Get Voltage in volts and a boolean that returns true if AC */
+  /**
+   * Get voltage in volts and a boolean indicating whether the voltage is AC
+   * (true) or DC (false).
+   *
+   * @example
+   *
+   * ```ts
+   * const powerSensor = new VIAM.PowerSensorClient(
+   *   machine,
+   *   'my_power_sensor'
+   * );
+   * const [voltage, isAc] = await powerSensor.getVoltage();
+   * ```
+   */
   getVoltage(extra?: Struct): Promise<readonly [number, boolean]>;
-  /** Get Current in amps and a boolean that returns true if AC */
+  /**
+   * Get Current in amps and a boolean indicating whether the voltage is AC
+   * (true) or DC (false).
+   *
+   * @example
+   *
+   * ```ts
+   * const powerSensor = new VIAM.PowerSensorClient(
+   *   machine,
+   *   'my_power_sensor'
+   * );
+   * const [current, isAc] = await powerSensor.getCurrent();
+   * ```
+   */
   getCurrent(extra?: Struct): Promise<readonly [number, boolean]>;
-  /** Get Power in watts */
+  /**
+   * Get power in watts.
+   *
+   * @example
+   *
+   * ```ts
+   * const powerSensor = new VIAM.PowerSensorClient(
+   *   machine,
+   *   'my_power_sensor'
+   * );
+   * const power = await powerSensor.getPower();
+   * ```
+   */
   getPower(extra?: Struct): Promise<number>;
-  /** Return the readings of a sensor. */
+  /**
+   * Return the readings of a sensor.
+   *
+   * @example
+   *
+   * ```ts
+   * const powerSensor = new VIAM.PowerSensorClient(
+   *   machine,
+   *   'my_power_sensor'
+   * );
+   * const readings = await powerSensor.getReadings();
+   * ```
+   */
   getReadings(extra?: Struct): Promise<Record<string, JsonValue>>;
 }

src/components/sensor/sensor.ts

@@ -3,6 +3,17 @@ import type { Resource } from '../../types';
 
 /** Represents a physical sensing device that can provide measurement readings. */
 export interface Sensor extends Resource {
-  /** Return the readings of a sensor. */
+  /**
+   * Return the readings of a sensor.
+   *
+   * @example
+   *
+   * ```ts
+   * const sensor = new VIAM.SensorClient(machine, 'my_sensor');
+   *
+   * // Get the readings of a sensor.
+   * const readings = await sensor.getReadings();
+   * ```
+   */
   getReadings(extra?: Struct): Promise<Record<string, JsonValue>>;
 }

src/types.ts

@@ -14,6 +14,15 @@ export interface Resource {
   /**
    * Send/Receive arbitrary commands to the resource.
    *
+   * @example
+   *
+   * ```ts
+   * const result = await resource.doCommand({
+   *   name: 'myCommand',
+   *   args: { key: 'value' },
+   * });
+   * ```
+   *
    * @param command - The command to execute.
    */
   doCommand(command: Struct): Promise<JsonValue>;