[commands] Improve documentation of addRequirements (NFC) (#5103)

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/CommandBase.java

@@ -26,7 +26,11 @@ public abstract class CommandBase implements Sendable, Command {
   }
 
   /**
-   * Adds the specified requirements to the command.
+   * Adds the specified subsystems to the requirements of the command. The scheduler will prevent
+   * two commands that require the same subsystem from being scheduled simultaneously.
+   *
+   * <p>Note that the scheduler determines the requirements of a command when it is scheduled, so
+   * this method should normally be called from the command's constructor.
    *
    * @param requirements the requirements to add
    */

wpilibNewCommands/src/main/native/include/frc2/command/CommandBase.h

@@ -28,6 +28,13 @@ class CommandBase : public Command,
   /**
    * Adds the specified Subsystem requirements to the command.
    *
+   * The scheduler will prevent two commands that require the same subsystem
+   * from being scheduled simultaneously.
+   *
+   * Note that the scheduler determines the requirements of a command when it
+   * is scheduled, so this method should normally be called from the command's
+   * constructor.
+   *
    * @param requirements the Subsystem requirements to add
    */
   void AddRequirements(std::initializer_list<Subsystem*> requirements);
@@ -35,6 +42,13 @@ class CommandBase : public Command,
   /**
    * Adds the specified Subsystem requirements to the command.
    *
+   * The scheduler will prevent two commands that require the same subsystem
+   * from being scheduled simultaneously.
+   *
+   * Note that the scheduler determines the requirements of a command when it
+   * is scheduled, so this method should normally be called from the command's
+   * constructor.
+   *
    * @param requirements the Subsystem requirements to add
    */
   void AddRequirements(std::span<Subsystem* const> requirements);
@@ -42,6 +56,13 @@ class CommandBase : public Command,
   /**
    * Adds the specified Subsystem requirements to the command.
    *
+   * The scheduler will prevent two commands that require the same subsystem
+   * from being scheduled simultaneously.
+   *
+   * Note that the scheduler determines the requirements of a command when it
+   * is scheduled, so this method should normally be called from the command's
+   * constructor.
+   *
    * @param requirements the Subsystem requirements to add
    */
   void AddRequirements(wpi::SmallSet<Subsystem*, 4> requirements);
@@ -49,6 +70,13 @@ class CommandBase : public Command,
   /**
    * Adds the specified Subsystem requirement to the command.
    *
+   * The scheduler will prevent two commands that require the same subsystem
+   * from being scheduled simultaneously.
+   *
+   * Note that the scheduler determines the requirements of a command when it
+   * is scheduled, so this method should normally be called from the command's
+   * constructor.
+   *
    * @param requirement the Subsystem requirement to add
    */
   void AddRequirements(Subsystem* requirement);