From 1416fb8f67e7e8127e0be3c3a53d6e16c9e78d45 Mon Sep 17 00:00:00 2001
From: Austin Shalit <austinshalit@gmail.com>
Date: Wed, 14 Sep 2016 00:21:25 -0400
Subject: [PATCH] Update Periodic JavaDoc (#231)

---
 wpilibc/athena/include/IterativeRobot.h       |  8 ++--
 wpilibc/athena/src/IterativeRobot.cpp         | 44 ++++++++++++++-----
 .../edu/wpi/first/wpilibj/IterativeRobot.java | 44 ++++++++++++++-----
 3 files changed, 71 insertions(+), 25 deletions(-)

diff --git a/wpilibc/athena/include/IterativeRobot.h b/wpilibc/athena/include/IterativeRobot.h
index 421a466c0e..07d1a01c3e 100644
--- a/wpilibc/athena/include/IterativeRobot.h
+++ b/wpilibc/athena/include/IterativeRobot.h
@@ -33,11 +33,9 @@
  *  - TestInit()       -- called each and every time test is entered from
  *                        another mode
  *
- * Periodic() functions -- each of these functions is called iteratively at the
- *                         appropriate periodic rate (aka the "slow loop").  The
- *                         default period of the iterative robot is synced to
- *                         the driver station control packets, giving a periodic
- *                         frequency of about 50Hz (50 times per second).
+ * Periodic() functions -- each of these functions is called each time a
+ *                         new packet is received from the driver station:
+ *   - RobotPeriodic()
  *   - DisabledPeriodic()
  *   - AutonomousPeriodic()
  *   - TeleopPeriodic()
diff --git a/wpilibc/athena/src/IterativeRobot.cpp b/wpilibc/athena/src/IterativeRobot.cpp
index 6ec24c36c9..9853d87bc1 100644
--- a/wpilibc/athena/src/IterativeRobot.cpp
+++ b/wpilibc/athena/src/IterativeRobot.cpp
@@ -164,8 +164,12 @@ void IterativeRobot::TestInit() {
 /**
  * Periodic code for all modes should go here.
  *
- * Users should override this method for code which will be called periodically
- * at a regular rate while the robot is in any mode.
+ * This function is called each time a new packet is received from the driver station.
+ *
+ * Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+ * network timing variability and the function may not be called at all if the Driver Station is
+ * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+ * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
  */
 void IterativeRobot::RobotPeriodic() {
   static bool firstRun = true;
@@ -178,8 +182,13 @@ void IterativeRobot::RobotPeriodic() {
 /**
  * Periodic code for disabled mode should go here.
  *
- * Users should override this method for code which will be called periodically
- * at a regular rate while the robot is in disabled mode.
+ * Users should override this method for code which will be called each time a new packet is
+ * received from the driver station and the robot is in disabled mode.
+ *
+ * Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+ * network timing variability and the function may not be called at all if the Driver Station is
+ * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+ * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
  */
 void IterativeRobot::DisabledPeriodic() {
   static bool firstRun = true;
@@ -192,8 +201,13 @@ void IterativeRobot::DisabledPeriodic() {
 /**
  * Periodic code for autonomous mode should go here.
  *
- * Users should override this method for code which will be called periodically
- * at a regular rate while the robot is in autonomous mode.
+ * Users should override this method for code which will be called each time a new packet is
+ * received from the driver station and the robot is in autonomous mode.
+ *
+ * Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+ * network timing variability and the function may not be called at all if the Driver Station is
+ * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+ * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
  */
 void IterativeRobot::AutonomousPeriodic() {
   static bool firstRun = true;
@@ -206,8 +220,13 @@ void IterativeRobot::AutonomousPeriodic() {
 /**
  * Periodic code for teleop mode should go here.
  *
- * Users should override this method for code which will be called periodically
- * at a regular rate while the robot is in teleop mode.
+ * Users should override this method for code which will be called each time a new packet is
+ * received from the driver station and the robot is in teleop mode.
+ *
+ * Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+ * network timing variability and the function may not be called at all if the Driver Station is
+ * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+ * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
  */
 void IterativeRobot::TeleopPeriodic() {
   static bool firstRun = true;
@@ -220,8 +239,13 @@ void IterativeRobot::TeleopPeriodic() {
 /**
  * Periodic code for test mode should go here.
  *
- * Users should override this method for code which will be called periodically
- * at a regular rate while the robot is in test mode.
+ * Users should override this method for code which will be called each time a new packet is
+ * received from the driver station and the robot is in test mode.
+ *
+ * Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+ * network timing variability and the function may not be called at all if the Driver Station is
+ * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+ * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
  */
 void IterativeRobot::TestPeriodic() {
   static bool firstRun = true;
diff --git a/wpilibj/src/athena/java/edu/wpi/first/wpilibj/IterativeRobot.java b/wpilibj/src/athena/java/edu/wpi/first/wpilibj/IterativeRobot.java
index ef797bcf03..d6b2ebdbf2 100644
--- a/wpilibj/src/athena/java/edu/wpi/first/wpilibj/IterativeRobot.java
+++ b/wpilibj/src/athena/java/edu/wpi/first/wpilibj/IterativeRobot.java
@@ -211,8 +211,12 @@ public class IterativeRobot extends RobotBase {
   /**
    * Periodic code for all robot modes should go here.
    *
-   * <p>Users should override this method for code which will be called periodically at a regular
-   * rate while the robot is in any mode.
+   * <p>This function is called each time a new packet is received from the driver station.
+   *
+   * <p>Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+   * network timing variability and the function may not be called at all if the Driver Station is
+   * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+   * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
    */
   public void robotPeriodic() {
     if (m_rpFirstRun) {
@@ -227,8 +231,13 @@ public class IterativeRobot extends RobotBase {
   /**
    * Periodic code for disabled mode should go here.
    *
-   * <p>Users should override this method for code which will be called periodically at a regular
-   * rate while the robot is in disabled mode.
+   * <p>Users should override this method for code which will be called each time a new packet is
+   * received from the driver station and the robot is in disabled mode.
+   *
+   * <p>Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+   * network timing variability and the function may not be called at all if the Driver Station is
+   * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+   * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
    */
   public void disabledPeriodic() {
     if (m_dpFirstRun) {
@@ -243,8 +252,13 @@ public class IterativeRobot extends RobotBase {
   /**
    * Periodic code for autonomous mode should go here.
    *
-   * <p>Users should override this method for code which will be called periodically at a regular
-   * rate while the robot is in autonomous mode.
+   * <p>Users should override this method for code which will be called each time a new packet is
+   * received from the driver station and the robot is in autonomous mode.
+   *
+   * <p>Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+   * network timing variability and the function may not be called at all if the Driver Station is
+   * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+   * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
    */
   public void autonomousPeriodic() {
     if (m_apFirstRun) {
@@ -259,8 +273,13 @@ public class IterativeRobot extends RobotBase {
   /**
    * Periodic code for teleop mode should go here.
    *
-   * <p>Users should override this method for code which will be called periodically at a regular
-   * rate while the robot is in teleop mode.
+   * <p>Users should override this method for code which will be called each time a new packet is
+   * received from the driver station and the robot is in teleop mode.
+   *
+   * <p>Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+   * network timing variability and the function may not be called at all if the Driver Station is
+   * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+   * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
    */
   public void teleopPeriodic() {
     if (m_tpFirstRun) {
@@ -275,8 +294,13 @@ public class IterativeRobot extends RobotBase {
   /**
    * Periodic code for test mode should go here.
    *
-   * <p>Users should override this method for code which will be called periodically at a regular
-   * rate while the robot is in test mode.
+   * <p>Users should override this method for code which will be called each time a new packet is
+   * received from the driver station and the robot is in test mode.
+   *
+   * <p>Packets are received approximately every 20ms.  Fixed loop timing is not guaranteed due to
+   * network timing variability and the function may not be called at all if the Driver Station is
+   * disconnected.  For most use cases the variable timing will not be an issue.  If your code does
+   * require guaranteed fixed periodic timing, consider using Notifier or PIDController instead.
    */
   public void testPeriodic() {
     if (m_tmpFirstRun) {