Command::IsFinished() must be overriden by subclasses again (#353)

Documentation was added for InstantCommand and TimedCommand.

wpilibc/shared/include/Commands/Command.h

@@ -84,7 +84,25 @@ class Command : public ErrorBase, public NamedSendable, public ITableListener {
 
   virtual void Initialize();
   virtual void Execute();
-  virtual bool IsFinished();
+
+  /**
+   * Returns whether this command is finished.
+   * If it is, then the command will be removed and {@link Command#end() end()}
+   * will be called.
+   *
+   * <p>It may be useful for a team to reference the {@link Command#isTimedOut()
+   * isTimedOut()} method for time-sensitive commands.</p>
+   *
+   * <p>Returning false will result in the command never ending automatically.
+   * It may still be cancelled manually or interrupted by another command.
+   * Returning true will result in the command executing once and finishing
+   * immediately. We recommend using {@link InstantCommand} for this.</p>
+   *
+   * @return whether this command is finished.
+   * @see Command#isTimedOut() isTimedOut()
+   */
+  virtual bool IsFinished() = 0;
+
   virtual void End();
   virtual void Interrupted();
 

wpilibc/shared/include/Commands/InstantCommand.h

@@ -13,6 +13,12 @@
 
 namespace frc {
 
+/**
+ * This command will execute once, then finish immediately afterward.
+ *
+ * <p>Subclassing {@link InstantCommand} is shorthand for returning true from
+ * {@link Command isFinished}.
+ */
 class InstantCommand : public Command {
  public:
   explicit InstantCommand(const std::string& name);
@@ -20,7 +26,7 @@ class InstantCommand : public Command {
   virtual ~InstantCommand() = default;
 
  protected:
-  virtual bool IsFinished();
+  bool IsFinished() override;
 };
 
 }  // namespace frc

wpilibc/shared/include/Commands/TimedCommand.h

@@ -13,6 +13,10 @@
 
 namespace frc {
 
+/**
+ * A {@link TimedCommand} will wait for a timeout before finishing.
+ * {@link TimedCommand} is used to execute a command for a given amount of time.
+ */
 class TimedCommand : public Command {
  public:
   TimedCommand(const std::string& name, double timeout);
@@ -20,7 +24,7 @@ class TimedCommand : public Command {
   virtual ~TimedCommand() = default;
 
  protected:
-  virtual bool IsFinished();
+  bool IsFinished() override;
 };
 
 }  // namespace frc

wpilibc/shared/src/Commands/Command.cpp

@@ -207,24 +207,6 @@ void Command::Execute() {}
  */
 void Command::End() {}
 
-/**
- * Returns whether this command is finished.
- * If it is, then the command will be removed and {@link Command#end() end()}
- * will be called.
- *
- * <p>It may be useful for a team to reference the {@link Command#isTimedOut()
- * isTimedOut()} method for time-sensitive commands.</p>
- *
- * <p>By default this will always return false, which means it will never end
- * automatically. It may still be cancelled manually or interrupted by another
- * command. For most real-world scenarios you will override this method with
- * additional logic.</p>
- *
- * @return whether this command is finished.
- * @see Command#isTimedOut() isTimedOut()
- */
-bool Command::IsFinished() { return false; }
-
 /**
  * Called when the command ends because somebody called
  * {@link Command#cancel() cancel()} or another command shared the same

wpilibc/shared/src/Commands/InstantCommand.cpp

@@ -9,6 +9,10 @@
 
 using namespace frc;
 
+/**
+ * Creates a new {@link InstantCommand} with the given name.
+ * @param name the name for this command
+ */
 InstantCommand::InstantCommand(const std::string& name) : Command(name) {}
 
 bool InstantCommand::IsFinished() { return true; }

wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/Command.java

@@ -277,16 +277,15 @@ public abstract class Command implements NamedSendable {
    * <p>It may be useful for a team to reference the {@link Command#isTimedOut() isTimedOut()}
    * method for time-sensitive commands.
    *
-   * <p>By default this will always return false, which means it will never end automatically. It
-   * may still be cancelled manually or interrupted by another command. For most real-world
-   * scenarios you will override this method with additional logic.
+   * <p>Returning false will result in the command never ending automatically. It may still be
+   * cancelled manually or interrupted by another command. Returning true will result in the
+   * command executing once and finishing immediately. We recommend using {@link InstantCommand}
+   * for this.
    *
    * @return whether this command is finished.
    * @see Command#isTimedOut() isTimedOut()
    */
-  protected boolean isFinished() {
-    return false;
-  }
+  protected abstract boolean isFinished();
 
   /**
    * Called when the command ended peacefully. This is where you may want to wrap up loose ends,

wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/InstantCommand.java

@@ -7,10 +7,21 @@
 
 package edu.wpi.first.wpilibj.command;
 
+/**
+ * This command will execute once, then finish immediately afterward.
+ *
+ * <p>Subclassing {@link InstantCommand} is shorthand for returning true from
+ * {@link Command isFinished}.
+ */
 public class InstantCommand extends Command {
+
   public InstantCommand() {
   }
 
+  /**
+   * Creates a new {@link InstantCommand InstantCommand} with the given name.
+   * @param name the name for this command
+   */
   public InstantCommand(String name) {
     super(name);
   }

wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/TimedCommand.java

@@ -7,6 +7,10 @@
 
 package edu.wpi.first.wpilibj.command;
 
+/**
+ * A {@link TimedCommand} will wait for a timeout before finishing.
+ * {@link TimedCommand} is used to execute a command for a given amount of time.
+ */
 public class TimedCommand extends Command {
   public TimedCommand(String name, double timeout) {
     super(name, timeout);