[commands] Disambiguate ProxyCommand and DeferredCommand (#6324)

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 <a
+   *     href="https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#scheduling-other-commands">WPILib
+   *     docs</a>
    */
   public ProxyCommand asProxy() {
     return new ProxyCommand(this);

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.
  *
  * <p>Note that the supplier <i>must</i> 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 <i>must</i> 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 <i>must</i> create a new Command each call.
    *
    * @param supplier The command supplier
    * @param requirements The command requirements. This is a {@link Set} to prevent accidental

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, <strong>but only if you know what you are doing. If you are unsure, see <a
+ * href="https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#scheduling-other-commands">the
+ * WPILib docs</a> for a complete explanation of proxy semantics.</strong> 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.
  *
  * <p>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 <strong>proxied</strong> 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<Command> supplier) {
     m_supplier = requireNonNullParam(supplier, "supplier", "ProxyCommand");

wpilibNewCommands/src/main/native/cpp/frc2/command/ProxyCommand.cpp

@@ -4,6 +4,7 @@
 
 #include "frc2/command/ProxyCommand.h"
 
+#include <fmt/core.h>
 #include <wpi/sendable/SendableBuilder.h>
 
 using namespace frc2;
@@ -20,11 +21,11 @@ ProxyCommand::ProxyCommand(wpi::unique_function<CommandPtr()> 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> command) {
-  SetName(std::string{"Proxy("}.append(command->GetName()).append(")"));
+  SetName(fmt::format("Proxy({})", command->GetName()));
   m_supplier = [command = std::move(command)] { return command.get(); };
 }
 

wpilibNewCommands/src/main/native/include/frc2/command/Command.h

@@ -249,14 +249,17 @@ class Command : public wpi::Sendable, public wpi::SendableHelper<Command> {
   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 <a
+   * href="https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#scheduling-other-commands">the
+   * WPILib docs</a> for a full explanation.
    *
    * <p>This overload transfers command ownership to the returned CommandPtr.
    *
    * @return the decorated command
+   * @see ProxyCommand
    */
   [[nodiscard]]
   CommandPtr AsProxy() &&;

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 <a
+   * href="https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#scheduling-other-commands">the
+   * WPILib docs</a> for a full explanation.
    *
    * @return the decorated command
+   * @see ProxyCommand
    */
   [[nodiscard]]
   CommandPtr AsProxy() &&;

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<Command, DeferredCommand> {
  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 <i>must</i> create a new Command each
    * call.
    *

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, <strong>but only if you know
+ * what you are doing. If you are unsure, see <a
+ * href="https://docs.wpilib.org/en/stable/docs/software/commandbased/command-compositions.html#scheduling-other-commands">the
+ * WPILib docs</a> for a complete explanation of proxy semantics.</strong> 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.
  *
  * <p>This class is provided by the NewCommands VendorDep
  */
@@ -23,19 +29,27 @@ class ProxyCommand : public CommandHelper<Command, ProxyCommand> {
  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 <strong>proxied</strong> 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<Command*()> 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 <strong>proxied</strong> 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<CommandPtr()> supplier);