[commands] Disambiguate ProxyCommand and DeferredCommand (#6324)

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