diff --git a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/Command.java b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/Command.java index 0186b6550d..3a5ee405f6 100644 --- a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/Command.java +++ b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/Command.java @@ -349,11 +349,16 @@ public abstract class Command implements Sendable { } /** - * Decorates this command to run "by proxy" by wrapping it in a {@link ProxyCommand}. This is - * useful for "forking off" from command compositions when the user does not wish to extend the - * command's requirements to the entire command composition. + * Decorates this command to run "by proxy" by wrapping it in a {@link ProxyCommand}. Use this for + * "forking off" from command compositions when the user does not wish to extend the command's + * requirements to the entire command composition. ProxyCommand has unique implications and + * semantics, see the WPILib docs for a full explanation. * * @return the decorated command + * @see ProxyCommand + * @see WPILib + * docs */ public ProxyCommand asProxy() { return new ProxyCommand(this); diff --git a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/DeferredCommand.java b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/DeferredCommand.java index 099eba3b04..f76cf90923 100644 --- a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/DeferredCommand.java +++ b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/DeferredCommand.java @@ -11,9 +11,9 @@ import java.util.Set; import java.util.function.Supplier; /** - * Defers Command construction to runtime. Runs the command returned by the supplier when this - * command is initialized, and ends when it ends. Useful for performing runtime tasks before - * creating a new command. If this command is interrupted, it will cancel the command. + * Defers Command construction to runtime. Runs the command returned by a supplier when this command + * is initialized, and ends when it ends. Useful for performing runtime tasks before creating a new + * command. If this command is interrupted, it will cancel the command. * *

Note that the supplier must create a new Command each call. For selecting one of a * preallocated set of commands, use {@link SelectCommand}. @@ -28,9 +28,10 @@ public class DeferredCommand extends Command { private Command m_command = m_nullCommand; /** - * Creates a new DeferredCommand that runs the supplied command when initialized, and ends when it - * ends. Useful for lazily creating commands at runtime. The {@link Supplier} will be called each - * time this command is initialized. The Supplier must create a new Command each call. + * Creates a new DeferredCommand that directly runs the supplied command when initialized, and + * ends when it ends. Useful for lazily creating commands when the DeferredCommand is initialized, + * such as if the supplied command depends on runtime state. The {@link Supplier} will be called + * each time this command is initialized. The Supplier must create a new Command each call. * * @param supplier The command supplier * @param requirements The command requirements. This is a {@link Set} to prevent accidental diff --git a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/ProxyCommand.java b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/ProxyCommand.java index f05b286f4d..f71c10b233 100644 --- a/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/ProxyCommand.java +++ b/wpilibNewCommands/src/main/java/edu/wpi/first/wpilibj2/command/ProxyCommand.java @@ -10,8 +10,13 @@ import edu.wpi.first.util.sendable.SendableBuilder; import java.util.function.Supplier; /** - * Schedules the given command when this command is initialized, and ends when it ends. Useful for - * forking off from CommandGroups. If this command is interrupted, it will cancel the command. + * Schedules a given command when this command is initialized and ends when it ends, but does not + * directly run it. Use this for including a command in a composition without adding its + * requirements, but only if you know what you are doing. If you are unsure, see the + * WPILib docs for a complete explanation of proxy semantics. Do not proxy a command + * from a subsystem already required by the composition, or else the composition will cancel itself + * when the proxy is reached. If this command is interrupted, it will cancel the command. * *

This class is provided by the NewCommands VendorDep */ @@ -21,9 +26,12 @@ public class ProxyCommand extends Command { /** * Creates a new ProxyCommand that schedules the supplied command when initialized, and ends when - * it is no longer scheduled. Useful for lazily creating commands at runtime. + * it is no longer scheduled. Use this for lazily creating proxied commands at + * runtime. Proxying should only be done to escape from composition requirement semantics, so if + * only initialization time command construction is needed, use {@link DeferredCommand} instead. * * @param supplier the command supplier + * @see DeferredCommand */ public ProxyCommand(Supplier supplier) { m_supplier = requireNonNullParam(supplier, "supplier", "ProxyCommand"); diff --git a/wpilibNewCommands/src/main/native/cpp/frc2/command/ProxyCommand.cpp b/wpilibNewCommands/src/main/native/cpp/frc2/command/ProxyCommand.cpp index eb4fb7cab1..3851afa53c 100644 --- a/wpilibNewCommands/src/main/native/cpp/frc2/command/ProxyCommand.cpp +++ b/wpilibNewCommands/src/main/native/cpp/frc2/command/ProxyCommand.cpp @@ -4,6 +4,7 @@ #include "frc2/command/ProxyCommand.h" +#include #include using namespace frc2; @@ -20,11 +21,11 @@ ProxyCommand::ProxyCommand(wpi::unique_function supplier) ProxyCommand::ProxyCommand(Command* command) : ProxyCommand([command] { return command; }) { - SetName(std::string{"Proxy("}.append(command->GetName()).append(")")); + SetName(fmt::format("Proxy({})", command->GetName())); } ProxyCommand::ProxyCommand(std::unique_ptr command) { - SetName(std::string{"Proxy("}.append(command->GetName()).append(")")); + SetName(fmt::format("Proxy({})", command->GetName())); m_supplier = [command = std::move(command)] { return command.get(); }; } diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/Command.h b/wpilibNewCommands/src/main/native/include/frc2/command/Command.h index ad6aa79040..27ac7f3582 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/Command.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/Command.h @@ -249,14 +249,17 @@ class Command : public wpi::Sendable, public wpi::SendableHelper { CommandPtr Repeatedly() &&; /** - * Decorates this command to run "by proxy" by wrapping it in a - * ProxyCommand. This is useful for "forking off" from command groups - * when the user does not wish to extend the command's requirements to the - * entire command group. + * Decorates this command to run "by proxy" by wrapping it in a ProxyCommand. + * Use this for "forking off" from command compositions when the user does not + * wish to extend the command's requirements to the entire command + * composition. ProxyCommand has unique implications and semantics, see the + * WPILib docs for a full explanation. * *

This overload transfers command ownership to the returned CommandPtr. * * @return the decorated command + * @see ProxyCommand */ [[nodiscard]] CommandPtr AsProxy() &&; diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/CommandPtr.h b/wpilibNewCommands/src/main/native/include/frc2/command/CommandPtr.h index a8d7cadd0d..f4548e4438 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/CommandPtr.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/CommandPtr.h @@ -50,12 +50,15 @@ class CommandPtr final { CommandPtr Repeatedly() &&; /** - * Decorates this command to run "by proxy" by wrapping it in a - * ProxyCommand. This is useful for "forking off" from command groups - * when the user does not wish to extend the command's requirements to the - * entire command group. + * Decorates this command to run "by proxy" by wrapping it in a ProxyCommand. + * Use this for "forking off" from command compositions when the user does not + * wish to extend the command's requirements to the entire command + * composition. ProxyCommand has unique implications and semantics, see the + * WPILib docs for a full explanation. * * @return the decorated command + * @see ProxyCommand */ [[nodiscard]] CommandPtr AsProxy() &&; diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/DeferredCommand.h b/wpilibNewCommands/src/main/native/include/frc2/command/DeferredCommand.h index 442076d8f2..28460fdf9b 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/DeferredCommand.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/DeferredCommand.h @@ -16,7 +16,7 @@ namespace frc2 { /** - * Defers Command construction to runtime. Runs the command returned by the + * Defers Command construction to runtime. Runs the command returned by a * supplier when this command is initialized, and ends when it ends. Useful for * performing runtime tasks before creating a new command. If this command is * interrupted, it will cancel the command. @@ -29,9 +29,10 @@ namespace frc2 { class DeferredCommand : public CommandHelper { public: /** - * Creates a new DeferredCommand that runs the supplied command when - * initialized, and ends when it ends. Useful for lazily - * creating commands at runtime. The supplier will be called each time this + * Creates a new DeferredCommand that directly runs the supplied command when + * initialized, and ends when it ends. Useful for lazily creating commands + * when the DeferredCommand is initialized, such as if the supplied command + * depends on runtime state. The supplier will be called each time this * command is initialized. The supplier must create a new Command each * call. * diff --git a/wpilibNewCommands/src/main/native/include/frc2/command/ProxyCommand.h b/wpilibNewCommands/src/main/native/include/frc2/command/ProxyCommand.h index 3b7eecc674..d4d4757cf4 100644 --- a/wpilibNewCommands/src/main/native/include/frc2/command/ProxyCommand.h +++ b/wpilibNewCommands/src/main/native/include/frc2/command/ProxyCommand.h @@ -13,9 +13,15 @@ namespace frc2 { /** - * Schedules the given command when this command is initialized, and ends when - * it ends. Useful for forking off from CommandGroups. If this command is - * interrupted, it will cancel the command. + * Schedules a given command when this command is initialized and ends when it + * ends, but does not directly run it. Use this for including a command in a + * composition without adding its requirements, but only if you know + * what you are doing. If you are unsure, see the + * WPILib docs for a complete explanation of proxy semantics. Do + * not proxy a command from a subsystem already required by the composition, or + * else the composition will cancel itself when the proxy is reached. If this + * command is interrupted, it will cancel the command. * *

This class is provided by the NewCommands VendorDep */ @@ -23,19 +29,27 @@ class ProxyCommand : public CommandHelper { public: /** * Creates a new ProxyCommand that schedules the supplied command when - * initialized, and ends when it is no longer scheduled. Useful for lazily - * creating commands at runtime. + * initialized, and ends when it is no longer scheduled. Use this for lazily + * creating proxied commands at runtime. Proxying should only + * be done to escape from composition requirement semantics, so if only + * initialization time command construction is needed, use {@link + * DeferredCommand} instead. * * @param supplier the command supplier + * @see DeferredCommand */ explicit ProxyCommand(wpi::unique_function supplier); /** * Creates a new ProxyCommand that schedules the supplied command when - * initialized, and ends when it is no longer scheduled. Useful for lazily - * creating commands at runtime. + * initialized, and ends when it is no longer scheduled. Use this for lazily + * creating proxied commands at runtime. Proxying should only + * be done to escape from composition requirement semantics, so if only + * initialization time command construction is needed, use {@link + * DeferredCommand} instead. * * @param supplier the command supplier + * @see DeferredCommand */ explicit ProxyCommand(wpi::unique_function supplier);