From 6dd937cef76298f0892995458ddc9242d9d33a86 Mon Sep 17 00:00:00 2001 From: Starlight220 <53231611+Starlight220@users.noreply.github.com> Date: Tue, 15 Nov 2022 00:21:35 +0200 Subject: [PATCH] [commands] Fix Trigger API docs (NFC) (#4599) --- .../wpilibj2/command/button/Trigger.java | 53 +++++++----- .../include/frc2/command/button/Trigger.h | 86 +++++++++++-------- 2 files changed, 78 insertions(+), 61 deletions(-) diff --git a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/button/Trigger.java b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/button/Trigger.java index b83150d1c5..3513ab6c1a 100644 --- a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/button/Trigger.java +++ b/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. + * + *

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. + * + *

Triggers can easily be composed for advanced functionality using the {@link + * #and(BooleanSupplier)}, {@link #or(BooleanSupplier)}, {@link #negate()} operators. * *

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. * - *

Polled by the {@link CommandScheduler#getDefaultButtonLoop() default scheduler button loop}. + *

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`. * - *

Doesn't re-start the command in-between. + *

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`. * - *

Does not re-start the command in-between. + *

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 diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h b/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h index ec39cd778a..4a7cecc042 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/button/Trigger.h +++ b/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 + *

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 + *

Triggers can easily be composed for advanced functionality using the + * {@link #operator!}, {@link #operator||}, {@link #operator&&} operators. + * + *

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. * *

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 isActive) + explicit Trigger(std::function 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 isActive) - : m_event{loop, std::move(isActive)} {} + Trigger(frc::EventLoop* loop, std::function 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`. * *

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`. * *

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`. * - *

Doesn't re-start the command in-between. + *

Doesn't re-start the command if it ends while the condition is still + * `true`. If the command should restart, see RepeatCommand. * *

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. + * + *

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`. * - *

Doesn't re-start the command in-between. + *

Doesn't re-start the command if it ends while the condition is still + * `true`. If the command should restart, see RepeatCommand. * *

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. + * + *

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`. * *

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`. * *

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. * *

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. * *

Takes a raw pointer, and so is non-owning; users are responsible for the