Document DeferredCommand and onlyIf/onlyWhile decorators#3130

Open

jasondaming wants to merge 3 commits intowpilibsuite:mainfrom

jasondaming:issue-2368-2252-document-command-decorators

Member

jasondaming commented Oct 8, 2025

Summary

Adds comprehensive documentation for three command decorators/factories that were missing from the command compositions documentation:

DeferredCommand / defer() factory
onlyIf() decorator
onlyWhile() decorator

Changes

Documents defer() factory backed by DeferredCommand for schedule-time command construction
Documents onlyIf() decorator for conditional command execution (runs only if condition is true)
Documents onlyWhile() decorator for commands that interrupt when condition becomes false
Includes code examples in Java, C++, and Python for all three decorators
Adds links to API documentation

Fixes #2368
Fixes #2252


          Document DeferredCommand and onlyIf/onlyWhile decorators

cae28ab

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

katzuv reviewed

View reviewed changes

source/docs/software/commandbased/command-compositions.rst Outdated

+                 ```java
+                 // Command will only run if the game piece is present
+                 button.onTrue(command.onlyIf(() -> intake.hasGamePiece()));

Contributor

katzuv Oct 11, 2025

Suggested change

      
               button.onTrue(command.onlyIf(() -> intake.hasGamePiece()));
          
               button.onTrue(command.onlyIf(intake::hasGamePiece));

source/docs/software/commandbased/command-compositions.rst Outdated

+                 ```python
+                 # Command will only run if the game piece is present
+                 button.onTrue(command.onlyIf(lambda: intake.hasGamePiece()))

Contributor

katzuv Oct 11, 2025

Suggested change

      
               button.onTrue(command.onlyIf(lambda: intake.hasGamePiece()))
          
               button.onTrue(command.onlyIf(intake.hasGamePiece))

@virtuald Is this suggested style for robotpy users?

Member

virtuald Oct 11, 2025

Sure.

Collaborator

sciencewhiz Oct 13, 2025

It looks like there's several more locations that need similar updates

source/docs/software/commandbased/command-compositions.rst

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

katzuv Oct 11, 2025

In that case, I think you'd use ConditionalCommand, which also evaluates the predicate at runtime.

source/docs/software/commandbased/command-compositions.rst Outdated

                  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

katzuv Oct 11, 2025

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.

source/docs/software/commandbased/command-compositions.rst Outdated

+                 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

katzuv Oct 11, 2025

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

source/docs/software/commandbased/command-compositions.rst Outdated


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

katzuv Oct 11, 2025

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

Starlight220 commented Oct 11, 2025 •

edited

Loading

See #2252 (comment)

It should be established that [onlyIf/onlyWhile] are logical complements of unless and until.

Perhaps even merge their sections

jasondaming and others added 2 commits

October 12, 2025 14:01


          Apply review feedback: fix API links and method references

c730670

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


          Fix broken Python API reference for defer()

87cbc3d

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>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet