[docs] Fix docs for SysID routine (#6164)

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/sysid/SysIdRoutine.java

@@ -151,10 +151,11 @@ public class SysIdRoutine extends SysIdRoutineLog {
      *
      * @param drive Sends the SysId-specified drive signal to the mechanism motors during test
      *     routines.
-     * @param log Returns measured data (voltages, positions, velocities) of the mechanism motors
+     * @param log Returns measured data of the mechanism motors during test routines. To return
-     *     during test routines. To return data, call `recordFrame` on the supplied
+     *     data, call `motor(string motorName)` on the supplied `SysIdRoutineLog` instance, and then
-     *     `SysIdRoutineLog` instance. Multiple motors can return data within a single `log`
+     *     call one or more of the chainable logging handles (e.g. `voltage`) on the returned
-     *     callback by calling `recordFrame` multiple times.
+     *     `MotorLog`. Multiple motors can be logged in a single callback by calling `motor`
+     *     multiple times.
      * @param subsystem The subsystem containing the motor(s) that is (or are) being characterized.
      *     Will be declared as a requirement for the returned test commands.
      * @param name The name of the mechanism being tested. Will be appended to the log entry title
@@ -178,10 +179,11 @@ public class SysIdRoutine extends SysIdRoutineLog {
      *
      * @param drive Sends the SysId-specified drive signal to the mechanism motors during test
      *     routines.
-     * @param log Returns measured data (voltages, positions, velocities) of the mechanism motors
+     * @param log Returns measured data of the mechanism motors during test routines. To return
-     *     during test routines. To return data, call `recordFrame` on the supplied
+     *     data, call `motor(string motorName)` on the supplied `SysIdRoutineLog` instance, and then
-     *     `SysIdRoutineLog` instance. Multiple motors can return data within a single `log`
+     *     call one or more of the chainable logging handles (e.g. `voltage`) on the returned
-     *     callback by calling `recordFrame` multiple times.
+     *     `MotorLog`. Multiple motors can be logged in a single callback by calling `motor`
+     *     multiple times.
      * @param subsystem The subsystem containing the motor(s) that is (or are) being characterized.
      *     Will be declared as a requirement for the returned test commands. The subsystem's `name`
      *     will be appended to the log entry title for the routine's test state, e.g.

wpilibNewCommands/src/main/native/include/frc2/command/sysid/SysIdRoutine.h

@@ -90,11 +90,13 @@ class Mechanism {
    * Create a new mechanism specification for a SysId routine.
    *
    * @param drive Sends the SysId-specified drive signal to the mechanism motors
-   *   during test routines.
+   * during test routines.
-   * @param log Returns measured data (voltages, positions, velocities) of the
+   * @param log Returns measured data of the mechanism motors during test
-   *   mechanism motors during test routines. To return data, call `RecordFrame`
+   * routines. To return data, call `Motor(string motorName)` on the supplied
-   *   on the supplied `MotorLog` instance. Multiple motors can return data
+   * `SysIdRoutineLog` instance, and then call one or more of the chainable
-   *   within a single `log` callback by calling `RecordFrame` multiple times.
+   * logging handles (e.g. `voltage`) on the returned `MotorLog`.  Multiple
+   * motors can be logged in a single callback by calling `Motor` multiple
+   * times.
    * @param subsystem The subsystem containing the motor(s) that is (or are)
    *   being characterized. Will be declared as a requirement for the returned
    *   test commands.
@@ -116,11 +118,13 @@ class Mechanism {
    * mechanism name to the subsystem name.
    *
    * @param drive Sends the SysId-specified drive signal to the mechanism motors
-   *   during test routines.
+   * during test routines.
-   * @param log Returns measured data (voltages, positions, velocities) of the
+   * @param log Returns measured data of the mechanism motors during test
-   *   mechanism motors during test routines. To return data, call `recordFrame`
+   * routines. To return data, call `Motor(string motorName)` on the supplied
-   *   on the supplied `MotorLog` instance. Multiple motors can return data
+   * `SysIdRoutineLog` instance, and then call one or more of the chainable
-   *   within a single `log` callback by calling `recordFrame` multiple times.
+   * logging handles (e.g. `voltage`) on the returned `MotorLog`.  Multiple
+   * motors can be logged in a single callback by calling `Motor` multiple
+   * times.
    * @param subsystem The subsystem containing the motor(s) that is (or are)
    *   being characterized. Will be declared as a requirement for the returned
    *   test commands. The subsystem's `name` will be appended to the log entry

wpilibc/src/main/native/include/frc/sysid/SysIdRoutineLog.h

@@ -46,46 +46,112 @@ class SysIdRoutineLog {
   using LogEntries = wpi::StringMap<MotorEntries>;
 
  public:
+  /** Logs data from a single motor during a SysIdRoutine. */
   class MotorLog {
    public:
-    MotorLog(std::string_view motorName, std::string_view logName,
+    /**
-             LogEntries* logEntries);
+     * Log a generic data value from the motor.
-
+     *
+     * @param name The name of the data field being recorded.
+     * @param value The numeric value of the data field.
+     * @param unit The unit string of the data field.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& value(std::string_view name, double value, std::string_view unit);
 
+    /**
+     * Log the voltage applied to the motor.
+     *
+     * @param voltage The voltage to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& voltage(units::volt_t voltage) {
       return value("voltage", voltage.value(), voltage.name());
     }
 
+    /**
+     * Log the linear position of the motor.
+     *
+     * @param position The linear position to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& position(units::meter_t position) {
       return value("position", position.value(), position.name());
     }
 
+    /**
+     * Log the angular position of the motor.
+     *
+     * @param position The angular position to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& position(units::turn_t position) {
       return value("position", position.value(), position.name());
     }
 
+    /**
+     * Log the linear velocity of the motor.
+     *
+     * @param velocity The linear velocity to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& velocity(units::meters_per_second_t velocity) {
       return value("velocity", velocity.value(), velocity.name());
     }
 
+    /**
+     * Log the angular velocity of the motor.
+     *
+     * @param velocity The angular velocity to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& velocity(units::turns_per_second_t velocity) {
       return value("velocity", velocity.value(), velocity.name());
     }
 
+    /**
+     * Log the linear acceleration of the motor.
+     *
+     * @param acceleration The linear acceleration to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& acceleration(units::meters_per_second_squared_t acceleration) {
       return value("acceleration", acceleration.value(), acceleration.name());
     }
 
+    /**
+     * Log the angular acceleration of the motor.
+     *
+     * @param acceleration The angular acceleration to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& acceleration(units::turns_per_second_squared_t acceleration) {
       return value("acceleration", acceleration.value(), acceleration.name());
     }
 
+    /**
+     * Log the current applied to the motor.
+     *
+     * @param current The current to record.
+     * @return The motor log (for call chaining).
+     */
     MotorLog& current(units::ampere_t current) {
       return value("current", current.value(), current.name());
     }
 
    private:
+    friend class SysIdRoutineLog;
+    /**
+     * Create a new SysId motor log handle.
+     *
+     * @param motorName The name of the motor whose data is being logged.
+     * @param logName The name of the SysIdRoutineLog that this motor belongs
+     * to.
+     * @param logEntries The DataLog entries of the SysIdRoutineLog that this
+     * motor belongs to.
+     */
+    MotorLog(std::string_view motorName, std::string_view logName,
+             LogEntries* logEntries);
     std::string m_motorName;
     std::string m_logName;
     LogEntries* m_logEntries;
@@ -110,6 +176,12 @@ class SysIdRoutineLog {
    */
   void RecordState(State state);
 
+  /**
+   * Log data from a motor during a SysId routine.
+   *
+   * @param motorName The name of the motor.
+   * @return Handle with chainable callbacks to log individual data fields.
+   */
   MotorLog Motor(std::string_view motorName);
 
   static std::string StateEnumToString(State state);

wpilibj/src/main/java/edu/wpi/first/wpilibj/sysid/SysIdRoutineLog.java

@@ -73,7 +73,7 @@ public class SysIdRoutineLog {
     }
   }
 
-  /** Allows logging of data for a single motor during a SysIdRoutine. */
+  /** Logs data from a single motor during a SysIdRoutine. */
   public class MotorLog {
     private final String m_motorName;
 
@@ -88,7 +88,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record a generic data value from this motor.
+     * Log a generic data value from the motor.
      *
      * @param name The name of the data field being recorded.
      * @param value The numeric value of the data field.
@@ -111,7 +111,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record a voltage value from this motor.
+     * Log the voltage applied to the motor.
      *
      * @param voltage The voltage to record.
      * @return The motor log (for call chaining).
@@ -121,7 +121,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record a linear position value from this motor.
+     * Log the linear position of the motor.
      *
      * @param position The linear position to record.
      * @return The motor log (for call chaining).
@@ -131,7 +131,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record an angular position value from this motor.
+     * Log the angular position of the motor.
      *
      * @param position The angular position to record.
      * @return The motor log (for call chaining).
@@ -141,7 +141,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record a linear velocity value from this motor.
+     * Log the linear velocity of the motor.
      *
      * @param velocity The linear velocity to record.
      * @return The motor log (for call chaining).
@@ -151,7 +151,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record an angular velocity value from this motor.
+     * Log the angular velocity of the motor.
      *
      * @param velocity The angular velocity to record.
      * @return The motor log (for call chaining).
@@ -161,7 +161,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record a linear acceleration value from this motor.
+     * Log the linear acceleration of the motor.
      *
      * @param acceleration The linear acceleration to record.
      * @return The motor log (for call chaining).
@@ -174,7 +174,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record an angular acceleration value from this motor.
+     * Log the angular acceleration of the motor.
      *
      * @param acceleration The angular acceleration to record.
      * @return The motor log (for call chaining).
@@ -187,7 +187,7 @@ public class SysIdRoutineLog {
     }
 
     /**
-     * Record a current value for this motor.
+     * Log the current applied to the motor.
      *
      * @param current The current to record.
      * @return The motor log (for call chaining).
@@ -199,10 +199,10 @@ public class SysIdRoutineLog {
   }
 
   /**
-   * Returns the logging handle for a given motor.
+   * Log data from a motor during a SysId routine.
    *
-   * @param motorName The name of the motor to log data from.
+   * @param motorName The name of the motor.
-   * @return The logging handle for the specified motor.
+   * @return Handle with chainable callbacks to log individual data fields.
    */
   public MotorLog motor(String motorName) {
     return new MotorLog(motorName);