[commands] Fix Trigger API docs (NFC) (#4599)

wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/button/Trigger.java

@@ -17,8 +17,13 @@ import java.util.function.BiFunction;
 import java.util.function.BooleanSupplier;
 
 /**
- * This class is a wrapper around {@link BooleanEvent}, providing an easy way to link commands to
- * digital inputs.
+ * This class provides an easy way to link commands to conditions.
+ *
+ * <p>It is very easy to link a button to a command. For instance, you could link the trigger button
+ * of a joystick to a "score" command.
+ *
+ * <p>Triggers can easily be composed for advanced functionality using the {@link
+ * #and(BooleanSupplier)}, {@link #or(BooleanSupplier)}, {@link #negate()} operators.
  *
  * <p>This class is provided by the NewCommands VendorDep
  */
@@ -26,13 +31,13 @@ public class Trigger implements BooleanSupplier {
   private final BooleanEvent m_event;
 
   /**
-   * Creates a new trigger with the given condition/digital signal.
+   * Creates a new trigger based on the given condition.
    *
-   * @param loop the loop that polls this trigger
-   * @param signal the digital signal represented.
+   * @param loop The loop instance that polls this trigger.
+   * @param condition the condition represented by this trigger
    */
-  public Trigger(EventLoop loop, BooleanSupplier signal) {
-    m_event = new BooleanEvent(loop, signal);
+  public Trigger(EventLoop loop, BooleanSupplier condition) {
+    m_event = new BooleanEvent(loop, condition);
   }
 
   /**
@@ -47,24 +52,24 @@ public class Trigger implements BooleanSupplier {
   }
 
   /**
-   * Creates a new trigger with the given condition/digital signal.
+   * Creates a new trigger based on the given condition.
    *
-   * <p>Polled by the {@link CommandScheduler#getDefaultButtonLoop() default scheduler button loop}.
+   * <p>Polled by the default scheduler button loop.
    *
-   * @param signal the digital signal represented.
+   * @param condition the condition represented by this trigger
    */
-  public Trigger(BooleanSupplier signal) {
-    this(CommandScheduler.getInstance().getDefaultButtonLoop(), signal);
+  public Trigger(BooleanSupplier condition) {
+    this(CommandScheduler.getInstance().getDefaultButtonLoop(), condition);
   }
 
-  /** Creates a new trigger that is always inactive. */
+  /** Creates a new trigger that is always `false`. */
   @Deprecated
   public Trigger() {
     this(() -> false);
   }
 
   /**
-   * Starts the given command whenever the signal rises from the low state to the high state.
+   * Starts the given command whenever the condition changes from `false` to `true`.
    *
    * @param command the command to start
    * @return this trigger, so calls can be chained
@@ -77,7 +82,7 @@ public class Trigger implements BooleanSupplier {
   }
 
   /**
-   * Starts the given command whenever the signal falls from the high state to the low state.
+   * Starts the given command whenever the condition changes from `true` to `false`.
    *
    * @param command the command to start
    * @return this trigger, so calls can be chained
@@ -90,10 +95,11 @@ public class Trigger implements BooleanSupplier {
   }
 
   /**
-   * Starts the given command when the signal rises to the high state and cancels it when the signal
-   * falls.
+   * Starts the given command when the condition changes to `true` and cancels it when the condition
+   * changes to `false`.
    *
-   * <p>Doesn't re-start the command in-between.
+   * <p>Doesn't re-start the command if it ends while the condition is still `true`. If the command
+   * should restart, see {@link edu.wpi.first.wpilibj2.command.RepeatCommand}.
    *
    * @param command the command to start
    * @return this trigger, so calls can be chained
@@ -106,10 +112,11 @@ public class Trigger implements BooleanSupplier {
   }
 
   /**
-   * Starts the given command when the signal falls to the low state and cancels it when the signal
-   * rises.
+   * Starts the given command when the condition changes to `false` and cancels it when the
+   * condition changes to `true`.
    *
-   * <p>Does not re-start the command in-between.
+   * <p>Doesn't re-start the command if it ends while the condition is still `false`. If the command
+   * should restart, see {@link edu.wpi.first.wpilibj2.command.RepeatCommand}.
    *
    * @param command the command to start
    * @return this trigger, so calls can be chained
@@ -122,7 +129,7 @@ public class Trigger implements BooleanSupplier {
   }
 
   /**
-   * Toggles a command when the signal rises from the low state to the high state.
+   * Toggles a command when the condition changes from `false` to `true`.
    *
    * @param command the command to toggle
    * @return this trigger, so calls can be chained
@@ -143,7 +150,7 @@ public class Trigger implements BooleanSupplier {
   }
 
   /**
-   * Toggles a command when the signal rises from the low state to the high state.
+   * Toggles a command when the condition changes from `true` to the low state.
    *
    * @param command the command to toggle
    * @return this trigger, so calls can be chained

wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h

@@ -22,46 +22,48 @@
 namespace frc2 {
 class Command;
 /**
- * This class is a command-based wrapper around {@link frc::BooleanEvent},
- * providing an easy way to link commands to inputs.
+ * This class provides an easy way to link commands to conditions.
  *
- * This class is provided by the NewCommands VendorDep
+ * <p>It is very easy to link a button to a command. For instance, you could
+ * link the trigger button of a joystick to a "score" command.
  *
- * @see Button
+ * <p>Triggers can easily be composed for advanced functionality using the
+ * {@link #operator!}, {@link #operator||}, {@link #operator&&} operators.
+ *
+ * <p>This class is provided by the NewCommands VendorDep
  */
 class Trigger {
  public:
   /**
-   * Creates a new trigger with the given condition determining whether it is
-   * active.
+   * Creates a new trigger based on the given condition.
    *
    * <p>Polled by the default scheduler button loop.
    *
-   * @param isActive returns whether or not the trigger should be active
+   * @param condition the condition represented by this trigger
    */
-  explicit Trigger(std::function<bool()> isActive)
+  explicit Trigger(std::function<bool()> condition)
       : m_event{CommandScheduler::GetInstance().GetDefaultButtonLoop(),
-                std::move(isActive)} {}
+                std::move(condition)} {}
 
   /**
-   * Create a new trigger that is active when the given condition is true.
+   * Creates a new trigger based on the given condition.
    *
    * @param loop The loop instance that polls this trigger.
-   * @param isActive Whether the trigger is active.
+   * @param condition the condition represented by this trigger
    */
-  Trigger(frc::EventLoop* loop, std::function<bool()> isActive)
-      : m_event{loop, std::move(isActive)} {}
+  Trigger(frc::EventLoop* loop, std::function<bool()> condition)
+      : m_event{loop, std::move(condition)} {}
 
   /**
-   * Create a new trigger that is never active (default constructor) - activity
-   *  can be further determined by subclass code.
+   * Create a new trigger that is always `false`.
    */
   Trigger() : Trigger([] { return false; }) {}
 
   Trigger(const Trigger& other);
 
   /**
-   * Starts the given command whenever the signal rises from `false` to `true`.
+   * Starts the given command whenever the condition changes from `false` to
+   * `true`.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
    * lifespan of the command.
@@ -73,8 +75,8 @@ class Trigger {
   Trigger OnTrue(Command* command);
 
   /**
-   * Starts the given command whenever the signal rises from `false` to `true`.
-   * Moves command ownership to the button scheduler.
+   * Starts the given command whenever the condition changes from `false` to
+   * `true`. Moves command ownership to the button scheduler.
    *
    * @param command The command to bind.
    * @return The trigger, for chained calls.
@@ -82,7 +84,8 @@ class Trigger {
   Trigger OnTrue(CommandPtr&& command);
 
   /**
-   * Starts the given command whenever the signal falls from `true` to `false`.
+   * Starts the given command whenever the condition changes from `true` to
+   * `false`.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
    * lifespan of the command.
@@ -94,7 +97,8 @@ class Trigger {
   Trigger OnFalse(Command* command);
 
   /**
-   * Starts the given command whenever the signal falls from `true` to `false`.
+   * Starts the given command whenever the condition changes from `true` to
+   * `false`.
    *
    * @param command The command to bind.
    * @return The trigger, for chained calls.
@@ -102,10 +106,11 @@ class Trigger {
   Trigger OnFalse(CommandPtr&& command);
 
   /**
-   * Starts the given command when the signal rises to `true` and cancels it
-   * when the signal falls to `false`.
+   * Starts the given command when the condition changes to `true` and cancels
+   * it when the condition changes to `false`.
    *
-   * <p>Doesn't re-start the command in-between.
+   * <p>Doesn't re-start the command if it ends while the condition is still
+   * `true`. If the command should restart, see RepeatCommand.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
    * lifespan of the command.
@@ -116,9 +121,12 @@ class Trigger {
   Trigger WhileTrue(Command* command);
 
   /**
-   * Starts the given command when the signal rises to `true` and cancels it
-   * when the signal falls to `false`. Moves command ownership to the button
-   * scheduler.
+   * Starts the given command when the condition changes to `true` and cancels
+   * it when the condition changes to `false`. Moves command ownership to the
+   * button scheduler.
+   *
+   * <p>Doesn't re-start the command if it ends while the condition is still
+   * `true`. If the command should restart, see RepeatCommand.
    *
    * @param command The command to bind.
    * @return The trigger, for chained calls.
@@ -126,10 +134,11 @@ class Trigger {
   Trigger WhileTrue(CommandPtr&& command);
 
   /**
-   * Starts the given command when the signal falls to `false` and cancels
-   * it when the signal rises.
+   * Starts the given command when the condition changes to `false` and cancels
+   * it when the condition changes to `true`.
    *
-   * <p>Doesn't re-start the command in-between.
+   * <p>Doesn't re-start the command if it ends while the condition is still
+   * `true`. If the command should restart, see RepeatCommand.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
    * lifespan of the command.
@@ -140,9 +149,12 @@ class Trigger {
   Trigger WhileFalse(Command* command);
 
   /**
-   * Starts the given command when the signal falls to `false` and cancels
-   * it when the signal rises. Moves command ownership to the button
-   * scheduler.
+   * Starts the given command when the condition changes to `false` and cancels
+   * it when the condition changes to `true`. Moves command ownership to the
+   * button scheduler.
+   *
+   * <p>Doesn't re-start the command if it ends while the condition is still
+   * `false`. If the command should restart, see RepeatCommand.
    *
    * @param command The command to bind.
    * @return The trigger, for chained calls.
@@ -150,8 +162,7 @@ class Trigger {
   Trigger WhileFalse(CommandPtr&& command);
 
   /**
-   * Toggles a command when the signal rises from `false` to the high
-   * state.
+   * Toggles a command when the condition changes from `false` to `true`.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
    * lifespan of the command.
@@ -162,8 +173,7 @@ class Trigger {
   Trigger ToggleOnTrue(Command* command);
 
   /**
-   * Toggles a command when the signal rises from `false` to the high
-   * state.
+   * Toggles a command when the condition changes from `false` to `true`.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
    * lifespan of the command.
@@ -174,7 +184,7 @@ class Trigger {
   Trigger ToggleOnTrue(CommandPtr&& command);
 
   /**
-   * Toggles a command when the signal falls from `true` to the low
+   * Toggles a command when the condition changes from `true` to the low
    * state.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the
@@ -186,7 +196,7 @@ class Trigger {
   Trigger ToggleOnFalse(Command* command);
 
   /**
-   * Toggles a command when the signal falls from `true` to the low
+   * Toggles a command when the condition changes from `true` to the low
    * state.
    *
    * <p>Takes a raw pointer, and so is non-owning; users are responsible for the