Document DeferredCommand and onlyIf/onlyWhile decorators - #3130
Open
jasondaming wants to merge 3 commits into
Open
Document DeferredCommand and onlyIf/onlyWhile decorators#3130jasondaming wants to merge 3 commits into
jasondaming wants to merge 3 commits into
Conversation
katzuv
reviewed
Oct 11, 2025
|
|
||
| ```java | ||
| // Command will only run if the game piece is present | ||
| button.onTrue(command.onlyIf(() -> intake.hasGamePiece())); |
Contributor
There was a problem hiding this comment.
Suggested change
| button.onTrue(command.onlyIf(() -> intake.hasGamePiece())); | |
| button.onTrue(command.onlyIf(intake::hasGamePiece)); |
|
|
||
| ```python | ||
| # Command will only run if the game piece is present | ||
| button.onTrue(command.onlyIf(lambda: intake.hasGamePiece())) |
Contributor
There was a problem hiding this comment.
Suggested change
| button.onTrue(command.onlyIf(lambda: intake.hasGamePiece())) | |
| button.onTrue(command.onlyIf(intake.hasGamePiece)) |
@virtuald Is this suggested style for robotpy users?
Collaborator
There was a problem hiding this comment.
It looks like there's several more locations that need similar updates
Comment on lines
+270
to
+292
| ```java | ||
| // Selects one of two commands based on current sensor state when scheduled | ||
| Commands.defer( | ||
| () -> sensor.get() ? Commands.print("Sensor true") : Commands.print("Sensor false"), | ||
| Set.of() | ||
| ) | ||
| ``` | ||
|
|
||
| ```c++ | ||
| // Selects one of two commands based on current sensor state when scheduled | ||
| frc2::cmd::Defer( | ||
| [&sensor] { return sensor.Get() ? frc2::cmd::Print("Sensor true") : frc2::cmd::Print("Sensor false"); }, | ||
| {} | ||
| ) | ||
| ``` | ||
|
|
||
| ```python | ||
| # Selects one of two commands based on current sensor state when scheduled | ||
| commands2.cmd.defer( | ||
| lambda: commands2.cmd.print_("Sensor true") if sensor.get() else commands2.cmd.print_("Sensor false"), | ||
| [] | ||
| ) | ||
| ``` |
Contributor
There was a problem hiding this comment.
In that case, I think you'd use ConditionalCommand, which also evaluates the predicate at runtime.
| button.onTrue(command.unless(lambda: not intake.isDeployed())) | ||
| ``` | ||
|
|
||
| The ``onlyIf()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyIf(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a73b3bb7908543e6ded5901adb0667c6d), :external:py:meth:`Python <commands2.Command.onlyIf>`) is similar to ``unless()`` but with inverted logic - the command will only run if the condition is true. |
Contributor
There was a problem hiding this comment.
Suggested change
| The ``onlyIf()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyIf(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a73b3bb7908543e6ded5901adb0667c6d), :external:py:meth:`Python <commands2.Command.onlyIf>`) is similar to ``unless()`` but with inverted logic - the command will only run if the condition is true. | |
| The ``onlyIf()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyIf(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a0c1b9e9e7cedd134145ee3d808bd92d2), :external:py:meth:`Python <commands2.Command.onlyIf>`) is similar to ``unless()`` but with inverted logic - the command will only run if the condition is true. |
| button.onTrue(command.onlyIf(lambda: intake.hasGamePiece())) | ||
| ``` | ||
|
|
||
| The ``onlyWhile()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyWhile(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a0ef33b5e59bf0f0b42010c8d6bec4d00), :external:py:meth:`Python <commands2.Command.onlyWhile>`) composes a command with a condition that is continuously checked during execution. If the condition becomes false while the command is running, the command will be interrupted. This is backed by a ``ParallelRaceGroup`` with a ``WaitUntilCommand``. |
Contributor
There was a problem hiding this comment.
Suggested change
| The ``onlyWhile()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyWhile(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#a0ef33b5e59bf0f0b42010c8d6bec4d00), :external:py:meth:`Python <commands2.Command.onlyWhile>`) composes a command with a condition that is continuously checked during execution. If the condition becomes false while the command is running, the command will be interrupted. This is backed by a ``ParallelRaceGroup`` with a ``WaitUntilCommand``. | |
| The ``onlyWhile()`` decorator ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Command.html#onlyWhile(java.util.function.BooleanSupplier)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_command_ptr.html#ab4917ac5eb58bd08eb2412070d29ba1c), :external:py:meth:`Python <commands2.Command.onlyWhile>`) composes a command with a condition that is continuously checked during execution. If the condition becomes false while the command is running, the command will be interrupted. This is backed by a ``ParallelRaceGroup`` with a ``WaitUntilCommand``. |
|
|
||
| ``ProxyCommand`` described below also has a constructor overload ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/ProxyCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_proxy_command.html), :external:py:class:`Python <commands2.ProxyCommand>`) that calls a command-returning lambda at schedule-time and runs the returned command by proxy. | ||
|
|
||
| The ``Defer`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#defer(java.util.function.Supplier,java.util.Set)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a03fe6ddac82ad3a4e1c086b1c0c23422), :external:py:func:`Python <commands2.cmd.defer>`), backed by the ``DeferredCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/DeferredCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_deferred_command.html), :external:py:class:`Python <commands2.DeferredCommand>`), defers command construction to schedule-time by calling a lambda that returns a command. Unlike ``ProxyCommand``, the deferred command runs inline within the composition, keeping everything within the composition instead of delegating to the scheduler. This should generally be preferred over the deferred ``ProxyCommand`` constructor. |
Contributor
There was a problem hiding this comment.
Suggested change
| The ``Defer`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#defer(java.util.function.Supplier,java.util.Set)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#a03fe6ddac82ad3a4e1c086b1c0c23422), :external:py:func:`Python <commands2.cmd.defer>`), backed by the ``DeferredCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/DeferredCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_deferred_command.html), :external:py:class:`Python <commands2.DeferredCommand>`), defers command construction to schedule-time by calling a lambda that returns a command. Unlike ``ProxyCommand``, the deferred command runs inline within the composition, keeping everything within the composition instead of delegating to the scheduler. This should generally be preferred over the deferred ``ProxyCommand`` constructor. | |
| The ``Defer`` factory ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/Commands.html#defer(java.util.function.Supplier,java.util.Set)), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/namespacefrc2_1_1cmd.html#ac177b5a1115cf55d575d5295c25ab7d1), :external:py:func:`Python <commands2.cmd.defer>`), backed by the ``DeferredCommand`` class ([Java](https://github.wpilib.org/allwpilib/docs/release/java/edu/wpi/first/wpilibj2/command/DeferredCommand.html), [C++](https://github.wpilib.org/allwpilib/docs/release/cpp/classfrc2_1_1_deferred_command.html), :external:py:class:`Python <commands2.DeferredCommand>`), defers command construction to schedule-time by calling a lambda that returns a command. Unlike ``ProxyCommand``, the deferred command runs inline within the composition, keeping everything within the composition instead of delegating to the scheduler. This should generally be preferred over the deferred ``ProxyCommand`` constructor. |
Member
|
See #2252 (comment)
Perhaps even merge their sections |
Adds comprehensive documentation for: - DeferredCommand and defer() factory for schedule-time command construction - onlyIf() decorator for conditional command execution - onlyWhile() decorator for commands that interrupt when condition becomes false Includes examples in Java, C++, and Python for all three decorators. Fixes wpilibsuite#2368 Fixes wpilibsuite#2252
- Updated C++ onlyIf link to correct overload - Updated C++ onlyWhile link to correct overload - Updated C++ defer link to correct overload - Changed Java onlyIf example to use method reference (intake::hasGamePiece) - Changed Python onlyIf example to use method reference (intake.hasGamePiece) Co-authored-by: katzuv <katzuv@users.noreply.github.com>
Remove broken intersphinx link to commands2.cmd.defer which is not found in Python API documentation. Keep plain text 'Python' reference. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
jasondaming
force-pushed
the
issue-2368-2252-document-command-decorators
branch
from
May 10, 2026 04:31
87cbc3d to
254f396
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds comprehensive documentation for three command decorators/factories that were missing from the command compositions documentation:
DeferredCommand/defer()factoryonlyIf()decoratoronlyWhile()decoratorChanges
defer()factory backed byDeferredCommandfor schedule-time command constructiononlyIf()decorator for conditional command execution (runs only if condition is true)onlyWhile()decorator for commands that interrupt when condition becomes falseFixes #2368
Fixes #2252