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