Added somewhat thorough documentation to lib2813

Author: codingduck106

lib/src/main/java/com/team2813/lib2813/control/ControlMode.java

@@ -2,19 +2,106 @@
 
 import com.revrobotics.spark.SparkBase.ControlType;
 
+/**
+ * Enumeration defining standardized motor control modes for the team's control system.
+ * 
+ * <p>This enum provides a vendor-neutral abstraction over different motor controller
+ * control modes while maintaining compatibility with specific hardware implementations.
+ * Each control mode maps to the appropriate vendor-specific control type for seamless
+ * integration with different motor controller families.
+ * 
+ * <p>The enum currently includes mappings for REV Robotics SPARK controllers, with
+ * each mode corresponding to a specific {@link ControlType} from the SPARK API.
+ * Additional vendor mappings can be added as needed.
+ * 
+ * <p>Supported control modes:
+ * <ul>
+ * <li><b>DUTY_CYCLE:</b> Open-loop duty cycle control (percentage output)</li>
+ * <li><b>VELOCITY:</b> Closed-loop velocity control with PID feedback</li>
+ * <li><b>MOTION_MAGIC:</b> Closed-loop position control with motion profiling</li>
+ * <li><b>VOLTAGE:</b> Open-loop voltage control</li>
+ * </ul>
+ * 
+ * @author Team 2813
+ * @since 1.0
+ */
 public enum ControlMode {
-  DUTY_CYCLE(ControlType.kDutyCycle),
-  VELOCITY(ControlType.kVelocity),
-  MOTION_MAGIC(ControlType.kPosition),
-  VOLTAGE(ControlType.kVoltage);
+    
+    /**
+     * Open-loop duty cycle control mode.
+     * 
+     * <p>Controls the motor by setting the duty cycle (percentage of full power) directly.
+     * The motor output is proportional to the demand value, typically ranging from
+     * -1.0 (full reverse) to +1.0 (full forward). This is the most basic control mode
+     * and does not use feedback control.
+     * 
+     * <p>Maps to {@link ControlType#kDutyCycle} for SPARK controllers.
+     */
+    DUTY_CYCLE(ControlType.kDutyCycle),
+    
+    /**
+     * Closed-loop velocity control mode.
+     * 
+     * <p>Controls the motor to maintain a specific velocity using PID feedback control.
+     * The controller continuously adjusts the motor output to minimize the error between
+     * the demanded velocity and the actual measured velocity from the encoder. This mode
+     * is ideal for applications requiring consistent speed regardless of load variations.
+     * 
+     * <p>Maps to {@link ControlType#kVelocity} for SPARK controllers.
+     */
+    VELOCITY(ControlType.kVelocity),
+    
+    /**
+     * Closed-loop position control mode with motion profiling.
+     * 
+     * <p>Controls the motor to reach a specific position using advanced motion profiling
+     * algorithms. The controller generates smooth velocity and acceleration profiles to
+     * move the mechanism to the target position while respecting configured motion
+     * constraints (max velocity, max acceleration). This mode provides the smoothest
+     * and most controlled movement for precise positioning applications.
+     * 
+     * <p>Maps to {@link ControlType#kPosition} for SPARK controllers.
+     * 
+     * <p><b>Note:</b> Despite the name "MOTION_MAGIC," this maps to position control
+     * type for SPARK controllers, as the motion profiling is handled internally.
+     */
+    MOTION_MAGIC(ControlType.kPosition),
+    
+    /**
+     * Open-loop voltage control mode.
+     * 
+     * <p>Controls the motor by applying a specific voltage directly to the motor terminals.
+     * Unlike duty cycle control, voltage control compensates for battery voltage variations
+     * to provide more consistent motor behavior. The demand value represents the desired
+     * voltage to apply to the motor.
+     * 
+     * <p>Maps to {@link ControlType#kVoltage} for SPARK controllers.
+     */
+    VOLTAGE(ControlType.kVoltage);
 
-  private final ControlType sparkMode;
+    /** The corresponding SPARK controller control type for this mode */
+    private final ControlType sparkMode;
 
-  ControlMode(ControlType sparkMode) {
-    this.sparkMode = sparkMode;
-  }
+    /**
+     * Creates a ControlMode with the specified SPARK controller mapping.
+     * 
+     * @param sparkMode the corresponding {@link ControlType} for SPARK controllers
+     */
+    ControlMode(ControlType sparkMode) {
+        this.sparkMode = sparkMode;
+    }
 
-  public ControlType getSparkMode() {
-    return sparkMode;
-  }
-}
+    /**
+     * Gets the corresponding SPARK controller control type for this mode.
+     * 
+     * <p>This method provides the mapping from the vendor-neutral ControlMode
+     * to the specific {@link ControlType} required by REV Robotics SPARK
+     * controllers. This abstraction allows the same control mode enum to be
+     * used across different motor controller implementations.
+     * 
+     * @return the corresponding {@link ControlType} for SPARK controllers
+     */
+    public ControlType getSparkMode() {
+        return sparkMode;
+    }
+}

lib/src/main/java/com/team2813/lib2813/control/DeviceInformation.java

@@ -3,59 +3,142 @@
 import com.team2813.lib2813.util.InputValidation;
 import java.util.Optional;
 
+/**
+ * Immutable value class representing the identifying information for a CAN device.
+ * 
+ * <p>This class encapsulates the essential information needed to uniquely identify
+ * a device on the CAN bus network: the CAN ID and the specific CAN bus the device
+ * is connected to. It provides a standardized way to represent device identity
+ * across the team's control system architecture.
+ * 
+ * <p>The class distinguishes between devices on the RoboRIO's built-in CAN bus
+ * (represented by an empty Optional for the canbus) and devices on named CAN buses
+ * such as CANivore or other CAN bus interfaces.
+ * 
+ * <p>Key features:
+ * <ul>
+ * <li>Immutable design for thread safety and reliable identity</li>
+ * <li>Input validation for CAN ID range [0, 62]</li>
+ * <li>Proper equals() and hashCode() implementation for use in collections</li>
+ * <li>Optional-based canbus representation for null safety</li>
+ * </ul>
+ * 
+ * <p>This class is commonly used as a key in device registries and for comparing
+ * device instances to determine if they represent the same physical hardware.
+ * 
+ * @author Team 2813
+ * @since 1.0
+ */
 public final class DeviceInformation {
-  private int id;
-  private Optional<String> canbus;
-
-  /**
-   * Creates a DeviceInformation for a device on the RoboRIO can loop
-   *
-   * @param id the can ID
-   */
-  public DeviceInformation(int id) {
-    this(id, null);
-  }
-
-  /**
-   * Creates a DeviceInformation with a canbus string. If {@code canbus} is {@code null}, method
-   * acts like {@link #DeviceInformation(int)} was called
-   *
-   * @param id the CAN id
-   * @param canbus the canbus string
-   */
-  public DeviceInformation(int id, String canbus) {
-    this.id = InputValidation.checkCanId(id);
-    this.canbus = Optional.ofNullable(canbus);
-  }
-
-  /**
-   * Gets the can id of this device
-   *
-   * @return the can id of the device
-   */
-  public int id() {
-    return id;
-  }
-
-  /**
-   * Returns the canbus that this device is on, or {@link Optional#empty()} if it is on the RoboRIO
-   * can loop
-   *
-   * @return the canbus that the device is on
-   */
-  public Optional<String> canbus() {
-    return canbus;
-  }
-
-  @Override
-  public boolean equals(Object o) {
-    if (!(o instanceof DeviceInformation)) return false;
-    DeviceInformation other = (DeviceInformation) o;
-    return other.id == id && other.canbus.equals(canbus);
-  }
-
-  @Override
-  public int hashCode() {
-    return id * 31 + canbus.hashCode();
-  }
-}
+    
+    /** The CAN ID of the device, validated to be in range [0, 62] */
+    private int id;
+    
+    /** The CAN bus name, empty if on the RoboRIO's default CAN bus */
+    private Optional<String> canbus;
+
+    /**
+     * Creates DeviceInformation for a device on the RoboRIO's default CAN bus.
+     * 
+     * <p>This constructor is used for devices connected directly to the RoboRIO's
+     * built-in CAN bus interface. The canbus will be represented as an empty
+     * Optional to indicate the default bus.
+     * 
+     * @param id the CAN ID of the device, must be in range [0, 62]
+     * @throws com.team2813.lib2813.util.InvalidCanIdException if the CAN ID is outside the valid range
+     */
+    public DeviceInformation(int id) {
+        this(id, null);
+    }
+
+    /**
+     * Creates DeviceInformation with a specific CAN bus name.
+     * 
+     * <p>This constructor supports devices on named CAN buses such as CANivore
+     * devices or other CAN bus interfaces. If {@code canbus} is {@code null},
+     * this method behaves identically to {@link #DeviceInformation(int)}.
+     * 
+     * <p>Examples of valid canbus names:
+     * <ul>
+     * <li>{@code "canivore"} - For CANivore devices</li>
+     * <li>{@code "CANivore_12345"} - For CANivore with specific serial number</li>
+     * <li>{@code null} - For RoboRIO default CAN bus</li>
+     * </ul>
+     * 
+     * @param id the CAN ID of the device, must be in range [0, 62]
+     * @param canbus the CAN bus name, or {@code null} for the RoboRIO default bus
+     * @throws com.team2813.lib2813.util.InvalidCanIdException if the CAN ID is outside the valid range
+     */
+    public DeviceInformation(int id, String canbus) {
+        this.id = InputValidation.checkCanId(id);
+        this.canbus = Optional.ofNullable(canbus);
+    }
+
+    /**
+     * Gets the CAN ID of this device.
+     * 
+     * <p>The CAN ID is guaranteed to be in the valid range [0, 62] due to
+     * validation performed during construction.
+     * 
+     * @return the CAN ID of the device
+     */
+    public int id() {
+        return id;
+    }
+
+    /**
+     * Returns the CAN bus that this device is connected to.
+     * 
+     * <p>The return value interpretation:
+     * <ul>
+     * <li>{@link Optional#empty()} - Device is on the RoboRIO's default CAN bus</li>
+     * <li>{@code Optional.of("busname")} - Device is on the named CAN bus</li>
+     * </ul>
+     * 
+     * <p>This Optional-based approach provides null safety and makes the
+     * distinction between default and named buses explicit in the API.
+     * 
+     * @return an Optional containing the CAN bus name, or empty if on the RoboRIO CAN bus
+     */
+    public Optional<String> canbus() {
+        return canbus;
+    }
+
+    /**
+     * Determines whether this DeviceInformation is equal to another object.
+     * 
+     * <p>Two DeviceInformation instances are considered equal if and only if
+     * they have the same CAN ID and are on the same CAN bus. This allows
+     * DeviceInformation objects to be used reliably as keys in hash-based
+     * collections and for device identity comparisons.
+     * 
+     * @param o the object to compare against
+     * @return {@code true} if the objects represent the same device,
+     *         {@code false} otherwise
+     */
+    @Override
+    public boolean equals(Object o) {
+        if (!(o instanceof DeviceInformation)) return false;
+        DeviceInformation other = (DeviceInformation) o;
+        return other.id == id && other.canbus.equals(canbus);
+    }
+
+    /**
+     * Returns a hash code value for this DeviceInformation.
+     * 
+     * <p>The hash code is computed from both the CAN ID and the CAN bus
+     * information, ensuring that equal DeviceInformation objects have
+     * equal hash codes. This implementation supports the use of
+     * DeviceInformation objects in hash-based collections such as
+     * HashMap and HashSet.
+     * 
+     * <p>The hash code formula combines the ID and canbus hash using
+     * a prime multiplier for good distribution properties.
+     * 
+     * @return a hash code value for this object
+     */
+    @Override
+    public int hashCode() {
+        return id * 31 + canbus.hashCode();
+    }
+}