From fd18577ba02a196ecd791125e3220e766eb4bdaa Mon Sep 17 00:00:00 2001
From: bovlb <31326650+bovlb@users.noreply.github.com>
Date: Thu, 16 Feb 2023 22:08:46 -0800
Subject: [PATCH] [commands] Improve documentation of addRequirements (NFC)
 (#5103)

---
 .../first/wpilibj2/command/CommandBase.java   |  6 +++-
 .../native/include/frc2/command/CommandBase.h | 28 +++++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/CommandBase.java b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/CommandBase.java
index 395322a996..5067a5a271 100644
--- a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/CommandBase.java
+++ b/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
    */
diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/CommandBase.h b/wpilibNewCommands/src/main/native/include/frc2/command/CommandBase.h
index 64bd88b7af..510d0000cf 100644
--- a/wpilibNewCommands/src/main/native/include/frc2/command/CommandBase.h
+++ b/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);