diff --git a/wpilibc/shared/include/Commands/Command.h b/wpilibc/shared/include/Commands/Command.h index a3d7beb979..f564b9a55a 100644 --- a/wpilibc/shared/include/Commands/Command.h +++ b/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. + * + *

It may be useful for a team to reference the {@link Command#isTimedOut() + * isTimedOut()} method for time-sensitive commands.

+ * + *

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() + */ + virtual bool IsFinished() = 0; + virtual void End(); virtual void Interrupted(); diff --git a/wpilibc/shared/include/Commands/InstantCommand.h b/wpilibc/shared/include/Commands/InstantCommand.h index b0d96d93d4..7cd685d48b 100644 --- a/wpilibc/shared/include/Commands/InstantCommand.h +++ b/wpilibc/shared/include/Commands/InstantCommand.h @@ -13,6 +13,12 @@ namespace frc { +/** + * This command will execute once, then finish immediately afterward. + * + *

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 diff --git a/wpilibc/shared/include/Commands/TimedCommand.h b/wpilibc/shared/include/Commands/TimedCommand.h index 246e5fb311..ef62815c08 100644 --- a/wpilibc/shared/include/Commands/TimedCommand.h +++ b/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 diff --git a/wpilibc/shared/src/Commands/Command.cpp b/wpilibc/shared/src/Commands/Command.cpp index b29ccd3e98..cff075e62f 100644 --- a/wpilibc/shared/src/Commands/Command.cpp +++ b/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. - * - *

It may be useful for a team to reference the {@link Command#isTimedOut() - * isTimedOut()} method for time-sensitive commands.

- * - *

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.

- * - * @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 diff --git a/wpilibc/shared/src/Commands/InstantCommand.cpp b/wpilibc/shared/src/Commands/InstantCommand.cpp index e1e57f97b1..fd8338457e 100644 --- a/wpilibc/shared/src/Commands/InstantCommand.cpp +++ b/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; } diff --git a/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/Command.java b/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/Command.java index fc0dc2e87f..31fb4486e2 100644 --- a/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/Command.java +++ b/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/Command.java @@ -277,16 +277,15 @@ public abstract class Command implements NamedSendable { *

It may be useful for a team to reference the {@link Command#isTimedOut() isTimedOut()} * method for time-sensitive commands. * - *

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. + *

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, diff --git a/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/InstantCommand.java b/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/InstantCommand.java index 6c6bee6394..507933eb13 100644 --- a/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/InstantCommand.java +++ b/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. + * + *

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); } diff --git a/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/TimedCommand.java b/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/TimedCommand.java index 4e038c3b62..11749f1cc0 100644 --- a/wpilibj/src/shared/java/edu/wpi/first/wpilibj/command/TimedCommand.java +++ b/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);