[wpilib] Improve MotorSafety documentation (NFC) (#4120)

Remove OBE RobotDrive porting guide from MecanumDrive

wpilibc/src/main/native/include/frc/MotorSafety.h

@@ -14,8 +14,11 @@
 namespace frc {
 
 /**
- * This base class runs a watchdog timer and calls the subclass's StopMotor()
- * function if the timeout expires.
+ * The Motor Safety feature acts as a watchdog timer for an individual motor. It
+ * operates by maintaining a timer that tracks how long it has been since the
+ * feed() method has been called for that actuator. Code in the Driver Station
+ * class initiates a comparison of these timers to the timeout values for any
+ * actuator with safety enabled every 5 received packets (100ms nominal).
  *
  * The subclass should call Feed() whenever the motor value is updated.
  */

wpilibc/src/main/native/include/frc/drive/DifferentialDrive.h

@@ -95,6 +95,10 @@ class SpeedController;
  * Inputs smaller then 0.02 will be set to 0, and larger values will be scaled
  * so that the full range is still used. This deadband value can be changed
  * with SetDeadband().
+ *
+ * MotorSafety is enabled by default. The tankDrive, arcadeDrive,
+ * or curvatureDrive methods should be called periodically to avoid Motor
+ * Safety timeouts.
  */
 class DifferentialDrive : public RobotDriveBase,
                           public wpi::Sendable,

wpilibc/src/main/native/include/frc/drive/KilloughDrive.h

@@ -53,6 +53,9 @@ class SpeedController;
  * The positive X axis points ahead, the positive Y axis points right, and the
  * and the positive Z axis points down. Rotations follow the right-hand rule, so
  * clockwise rotation around the Z axis is positive.
+ *
+ * MotorSafety is enabled by default. The DriveCartesian or DrivePolar
+ * methods should be called periodically to avoid Motor Safety timeouts.
  */
 class KilloughDrive : public RobotDriveBase,
                       public wpi::Sendable,

wpilibc/src/main/native/include/frc/drive/MecanumDrive.h

@@ -57,15 +57,8 @@ class SpeedController;
  * so that the full range is still used. This deadband value can be changed
  * with SetDeadband().
  *
- * RobotDrive porting guide:
- * <br>DriveCartesian(double, double, double, double) is equivalent to
- * RobotDrive's MecanumDrive_Cartesian(double, double, double, double)
- * if a deadband of 0 is used, and the ySpeed and gyroAngle values are inverted
- * compared to RobotDrive (eg DriveCartesian(xSpeed, -ySpeed, zRotation,
- * -gyroAngle).
- * <br>DrivePolar(double, double, double) is equivalent to
- * RobotDrive's MecanumDrive_Polar(double, double, double) if a
- * deadband of 0 is used.
+ * MotorSafety is enabled by default. The DriveCartesian or DrivePolar
+ * methods should be called periodically to avoid Motor Safety timeouts.
  */
 class MecanumDrive : public RobotDriveBase,
                      public wpi::Sendable,

wpilibc/src/main/native/include/frc/drive/RobotDriveBase.h

@@ -16,6 +16,8 @@ namespace frc {
 
 /**
  * Common base class for drive platforms.
+ *
+ * MotorSafety is enabled by default.
  */
 class RobotDriveBase : public MotorSafety {
  public:

wpilibj/src/main/java/edu/wpi/first/wpilibj/MotorSafety.java

@@ -8,8 +8,10 @@ import java.util.LinkedHashSet;
 import java.util.Set;
 
 /**
- * This base class runs a watchdog timer and calls the subclass's StopMotor() function if the
- * timeout expires.
+ * The Motor Safety feature acts as a watchdog timer for an individual motor. It operates by
+ * maintaining a timer that tracks how long it has been since the feed() method has been called for
+ * that actuator. Code in the Driver Station class initiates a comparison of these timers to the
+ * timeout values for any actuator with safety enabled every 5 received packets (100ms nominal).
  *
  * <p>The subclass should call feed() whenever the motor value is updated.
  */

wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/DifferentialDrive.java

@@ -83,6 +83,9 @@ import edu.wpi.first.wpilibj.SpeedController;
  * <p>Inputs smaller then {@value edu.wpi.first.wpilibj.drive.RobotDriveBase#kDefaultDeadband} will
  * be set to 0, and larger values will be scaled so that the full range is still used. This deadband
  * value can be changed with {@link #setDeadband}.
+ *
+ * <p>{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. The tankDrive, arcadeDrive,
+ * or curvatureDrive methods should be called periodically to avoid Motor Safety timeouts.
  */
 @SuppressWarnings("removal")
 public class DifferentialDrive extends RobotDriveBase implements Sendable, AutoCloseable {

wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/KilloughDrive.java

@@ -39,6 +39,9 @@ import edu.wpi.first.wpilibj.SpeedController;
  * <p>The positive X axis points ahead, the positive Y axis points right, and the positive Z axis
  * points down. Rotations follow the right-hand rule, so clockwise rotation around the Z axis is
  * positive.
+ *
+ * <p>{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. The driveCartesian or
+ * drivePolar methods should be called periodically to avoid Motor Safety timeouts.
  */
 @SuppressWarnings("removal")
 public class KilloughDrive extends RobotDriveBase implements Sendable, AutoCloseable {

wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/MecanumDrive.java

@@ -47,13 +47,8 @@ import edu.wpi.first.wpilibj.SpeedController;
  * be set to 0, and larger values will be scaled so that the full range is still used. This deadband
  * value can be changed with {@link #setDeadband}.
  *
- * <p>RobotDrive porting guide: <br>
- * {@link #driveCartesian(double, double, double, double)} is equivalent to RobotDrive's
- * mecanumDrive_Cartesian(double, double, double, double) if a deadband of 0 is used, and the ySpeed
- * and gyroAngle values are inverted compared to RobotDrive (eg driveCartesian(xSpeed, -ySpeed,
- * zRotation, -gyroAngle). <br>
- * {@link #drivePolar(double, double, double)} is equivalent to RobotDrive's
- * mecanumDrive_Polar(double, double, double)} if a deadband of 0 is used.
+ * <p>{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default. The driveCartesian or
+ * drivePolar methods should be called periodically to avoid Motor Safety timeouts.
  */
 @SuppressWarnings("removal")
 public class MecanumDrive extends RobotDriveBase implements Sendable, AutoCloseable {

wpilibj/src/main/java/edu/wpi/first/wpilibj/drive/RobotDriveBase.java

@@ -7,7 +7,11 @@ package edu.wpi.first.wpilibj.drive;
 import edu.wpi.first.math.MathUtil;
 import edu.wpi.first.wpilibj.MotorSafety;
 
-/** Common base class for drive platforms. */
+/**
+ * Common base class for drive platforms.
+ *
+ * <p>{@link edu.wpi.first.wpilibj.MotorSafety} is enabled by default.
+ */
 public abstract class RobotDriveBase extends MotorSafety {
   public static final double kDefaultDeadband = 0.02;
   public static final double kDefaultMaxOutput = 1.0;