From 1ad3b7c18a73bc0491f29ab27de0023e6e1daf5c Mon Sep 17 00:00:00 2001
From: Nilesh Agarwalla <nilesh@alum.mit.edu>
Date: Wed, 29 Nov 2023 11:05:32 -0500
Subject: [PATCH] Updated comments

---
 src/main/java/frc/robot/RobotContainer.java   |  5 +--
 .../java/frc/robot/commands/ArmCommand.java   | 34 +++++++++++++------
 src/main/java/frc/robot/subsystems/Arm.java   |  4 +++
 3 files changed, 30 insertions(+), 13 deletions(-)

diff --git a/src/main/java/frc/robot/RobotContainer.java b/src/main/java/frc/robot/RobotContainer.java
index bc525c5..87d582f 100644
--- a/src/main/java/frc/robot/RobotContainer.java
+++ b/src/main/java/frc/robot/RobotContainer.java
@@ -105,8 +105,9 @@ private void configureButtonBindings() {
 
     // START: Setup arm
     // Use the controller's right stick's forward/back (Y-axis) to control the arm base speed
-    // In this case, we want "forward" = "arm up", but forward is reported as a negative value from
-    // the stick, so we negate the returned value.
+    // In this case, we want "forward" = "arm up" = positive value, but forward is reported as a
+    // negative value from
+    // the controller's stick, so we negate the returned value.
     m_arm.setDefaultCommand(new ArmCommand(m_arm, () -> -m_controller.getRightY()));
     // END: Setup arm
   }
diff --git a/src/main/java/frc/robot/commands/ArmCommand.java b/src/main/java/frc/robot/commands/ArmCommand.java
index 980e113..efe7a16 100644
--- a/src/main/java/frc/robot/commands/ArmCommand.java
+++ b/src/main/java/frc/robot/commands/ArmCommand.java
@@ -6,18 +6,28 @@
 import java.util.function.DoubleSupplier;
 
 public class ArmCommand extends CommandBase {
-  private final Arm m_arm; // the arm subsystem used by this comment
-  private final DoubleSupplier m_baseSpeed; // the supplier of the desired speed
-  private final double m_defaultPosition =
-      0.5; // default start position for the arm when the command is first scheduled
-  private final double m_deadband =
-      0.05; // to prevent stick drift, this value sets the min absolute value the speed needs to be
+  // the arm subsystem used by this comment
+  private final Arm m_arm;
+
+  // the supplier of the desired speed
+  private final DoubleSupplier m_baseSpeed;
+
+  // default start position for the arm when the command is first scheduled
+  private final double m_defaultPosition = 0.5;
+
+  // to prevent stick drift, this value sets the min absolute value the speed needs to be
   // before we assume it is not zero
-  private final double m_speedScale =
-      16; // to reduce stick sensitivity, this value indicates how much to scale the returned speed
-  // by
-  private final double m_minBaseRange = -1; // min range for the arm's base
-  private final double m_maxBaseRange = 1; // max range for the arm's base
+  private final double m_deadband = 0.05;
+
+  // to reduce stick sensitivity, this value indicates how much to scale the requested
+  // speed.
+  private final double m_speedScale = 16;
+
+  // min range for the arm's base
+  private final double m_minBaseRange = -1;
+
+  // max range for the arm's base
+  private final double m_maxBaseRange = 1;
 
   public ArmCommand(Arm arm, DoubleSupplier baseSpeed) {
     m_arm = arm;
@@ -37,8 +47,10 @@ public void initialize() {
   public void execute() {
     // Variable that will store the new calculated arm position
     double newArmPosition;
+
     // Determine the requested speed, but ignoring inputs near-zero (i.e. +/= m_deadband)
     double currentShoulderSpeed = MathUtil.applyDeadband(m_baseSpeed.getAsDouble(), m_deadband);
+
     // Scale the speed as desired to reduce sensitivity
     currentShoulderSpeed /= m_speedScale;
 
diff --git a/src/main/java/frc/robot/subsystems/Arm.java b/src/main/java/frc/robot/subsystems/Arm.java
index 21a023f..2140ba7 100644
--- a/src/main/java/frc/robot/subsystems/Arm.java
+++ b/src/main/java/frc/robot/subsystems/Arm.java
@@ -16,6 +16,10 @@ public class Arm extends SubsystemBase {
   /**
    * Moves the arm base to the desired position. -1.0 is max down, and 1.0 is max up
    *
+   * <p>Note: The concept of "up and down" depends on how the servo is mounted to the arm. E.g. if
+   * the servo is flipped, the directions would be reversed. This module abstracts the hardware
+   * implementation details and follows the convention of 1.0 is up.
+   *
    * @param position desired target position for arm base [-1.0 to 1.0]
    */
   public void setArmBasePosition(double position) {