From f94e3d81b97f5822a1532e4e8474bb21a30b8470 Mon Sep 17 00:00:00 2001
From: Tyler Veness <calcmogul@gmail.com>
Date: Fri, 5 Jan 2024 16:03:52 -0800
Subject: [PATCH] [docs] Fix SysId routine JavaDoc warnings (#6159)

---
 .../wpilibj2/command/sysid/SysIdRoutine.java  | 19 ++++++++++++
 .../include/frc2/command/sysid/SysIdRoutine.h | 29 ++++++++++++++++++-
 .../include/frc/sysid/SysIdRoutineLog.h       |  9 +++++-
 .../first/wpilibj/sysid/SysIdRoutineLog.java  |  5 ++++
 4 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/sysid/SysIdRoutine.java b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/sysid/SysIdRoutine.java
index bac491da42..0e4541e1ca 100644
--- a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/sysid/SysIdRoutine.java
+++ b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/sysid/SysIdRoutine.java
@@ -61,9 +61,16 @@ public class SysIdRoutine extends SysIdRoutineLog {
 
   /** Hardware-independent configuration for a SysId test routine. */
   public static class Config {
+    /** The voltage ramp rate used for quasistatic test routines. */
     public final Measure<Velocity<Voltage>> m_rampRate;
+
+    /** The step voltage output used for dynamic test routines. */
     public final Measure<Voltage> m_stepVoltage;
+
+    /** Safety timeout for the test routine commands. */
     public final Measure<Time> m_timeout;
+
+    /** Optional handle for recording test state in a third-party logging solution. */
     public final Consumer<State> m_recordState;
 
     /**
@@ -124,9 +131,19 @@ public class SysIdRoutine extends SysIdRoutineLog {
    * routine to control and record data from the mechanism.
    */
   public static class Mechanism {
+    /** Sends the SysId-specified drive signal to the mechanism motors during test routines. */
     public final Consumer<Measure<Voltage>> m_drive;
+
+    /**
+     * Returns measured data (voltages, positions, velocities) of the mechanism motors during test
+     * routines.
+     */
     public final Consumer<SysIdRoutineLog> m_log;
+
+    /** The subsystem containing the motor(s) that is (or are) being characterized. */
     public final Subsystem m_subsystem;
+
+    /** The name of the mechanism being tested. */
     public final String m_name;
 
     /**
@@ -178,7 +195,9 @@ public class SysIdRoutine extends SysIdRoutineLog {
 
   /** Motor direction for a SysId test. */
   public enum Direction {
+    /** Forward. */
     kForward,
+    /** Reverse. */
     kReverse
   }
 
diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/sysid/SysIdRoutine.h b/wpilibNewCommands/src/main/native/include/frc2/command/sysid/SysIdRoutine.h
index c2177dd50d..8b90cdc6ba 100644
--- a/wpilibNewCommands/src/main/native/include/frc2/command/sysid/SysIdRoutine.h
+++ b/wpilibNewCommands/src/main/native/include/frc2/command/sysid/SysIdRoutine.h
@@ -23,9 +23,17 @@ using ramp_rate_t = units::unit_t<
 /** Hardware-independent configuration for a SysId test routine. */
 class Config {
  public:
+  /// The voltage ramp rate used for quasistatic test routines.
   ramp_rate_t m_rampRate{1_V / 1_s};
+
+  /// The step voltage output used for dynamic test routines.
   units::volt_t m_stepVoltage{7_V};
+
+  /// Safety timeout for the test routine commands.
   units::second_t m_timeout{10_s};
+
+  /// Optional handle for recording test state in a third-party logging
+  /// solution.
   std::function<void(frc::sysid::State)> m_recordState;
 
   /**
@@ -62,9 +70,20 @@ class Config {
 
 class Mechanism {
  public:
+  /// Sends the SysId-specified drive signal to the mechanism motors during test
+  /// routines.
   std::function<void(units::volt_t)> m_drive;
+
+  /// Returns measured data (voltages, positions, velocities) of the mechanism
+  /// motors during test routines.
   std::function<void(frc::sysid::SysIdRoutineLog*)> m_log;
+
+  /// The subsystem containing the motor(s) that is (or are) being
+  /// characterized.
   frc2::Subsystem* m_subsystem;
+
+  /// The name of the mechanism being tested. Will be appended to the log entry
+  /// title for the routine's test state, e.g. "sysid-test-state-mechanism".
   std::string m_name;
 
   /**
@@ -116,7 +135,15 @@ class Mechanism {
         m_name{m_subsystem->GetName()} {}
 };
 
-enum Direction { kForward, kReverse };
+/**
+ * Motor direction for a SysId test.
+ */
+enum Direction {
+  /// Forward.
+  kForward,
+  /// Reverse.
+  kReverse
+};
 
 /**
  * A SysId characterization routine for a single mechanism. Mechanisms may have
diff --git a/wpilibc/src/main/native/include/frc/sysid/SysIdRoutineLog.h b/wpilibc/src/main/native/include/frc/sysid/SysIdRoutineLog.h
index 401080bb9d..beaa8bf58b 100644
--- a/wpilibc/src/main/native/include/frc/sysid/SysIdRoutineLog.h
+++ b/wpilibc/src/main/native/include/frc/sysid/SysIdRoutineLog.h
@@ -20,12 +20,19 @@
 
 namespace frc::sysid {
 
-/** Possible state of a SysId routine. */
+/**
+ * Possible state of a SysId routine.
+ */
 enum class State {
+  /// Quasistatic forward test.
   kQuasistaticForward,
+  /// Quasistatic reverse test.
   kQuasistaticReverse,
+  /// Dynamic forward test.
   kDynamicForward,
+  /// Dynamic reverse test.
   kDynamicReverse,
+  /// No test.
   kNone
 };
 
diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/sysid/SysIdRoutineLog.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/sysid/SysIdRoutineLog.java
index d21baf74fd..a35cf75841 100644
--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/sysid/SysIdRoutineLog.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/sysid/SysIdRoutineLog.java
@@ -50,10 +50,15 @@ public class SysIdRoutineLog {
 
   /** Possible state of a SysId routine. */
   public enum State {
+    /** Quasistatic forward test. */
     kQuasistaticForward("quasistatic-forward"),
+    /** Quasistatic reverse test. */
     kQuasistaticReverse("quasistatic-reverse"),
+    /** Dynamic forward test. */
     kDynamicForward("dynamic-forward"),
+    /** Dynamic reverse test. */
     kDynamicReverse("dynamic-reverse"),
+    /** No test. */
     kNone("none");
 
     private final String m_state;