[wpilib] Improve interrupt docs (NFC) (#3679)

wpilibc/src/main/native/include/frc/AsynchronousInterrupt.h

@@ -16,7 +16,7 @@
 
 namespace frc {
 /**
- * Class for handling asynchronous interrupts.
+ * Class for handling asynchronous interrupts using a callback thread.
  *
  * <p> By default, interrupts will occur on rising edge. Callbacks are disabled
  * by default, and Enable() must be called before they will occur.
@@ -24,7 +24,8 @@ namespace frc {
  * <p> Both rising and falling edges can be indicated in one callback if both a
  * rising and falling edge occurred since the previous callback.
  *
- * <p>Synchronous interrupts are handled by the SynchronousInterrupt class.
+ * <p>Synchronous (blocking) interrupts are handled by the SynchronousInterrupt
+ * class.
  */
 class AsynchronousInterrupt {
  public:
@@ -33,7 +34,12 @@ class AsynchronousInterrupt {
    *
    * <p> At construction, the interrupt will trigger on the rising edge.
    *
-   * <p> The first bool in the callback is rising, the second is falling.
+   * <p> The first bool in the callback indicates the rising edge triggered the
+   * interrupt, the second bool is falling edge.
+   *
+   * @param source the DigitalSource the interrupts are triggered from
+   * @param callback the callback function to call when the interrupt is
+   * triggered
    */
   AsynchronousInterrupt(DigitalSource& source,
                         std::function<void(bool, bool)> callback);
@@ -43,7 +49,12 @@ class AsynchronousInterrupt {
    *
    * <p> At construction, the interrupt will trigger on the rising edge.
    *
-   * <p> The first bool in the callback is rising, the 2nd is falling.
+   * <p> The first bool in the callback indicates the rising edge triggered the
+   * interrupt, the second bool is falling edge.
+   *
+   * @param source the DigitalSource the interrupts are triggered from
+   * @param callback the callback function to call when the interrupt is
+   * triggered
    */
   AsynchronousInterrupt(DigitalSource* source,
                         std::function<void(bool, bool)> callback);
@@ -53,7 +64,12 @@ class AsynchronousInterrupt {
    *
    * <p> At construction, the interrupt will trigger on the rising edge.
    *
-   * <p> The first bool in the callback is rising, the 2nd is falling.
+   * <p> The first bool in the callback indicates the rising edge triggered the
+   * interrupt, the second bool is falling edge.
+   *
+   * @param source the DigitalSource the interrupts are triggered from
+   * @param callback the callback function to call when the interrupt is
+   * triggered
    */
   AsynchronousInterrupt(std::shared_ptr<DigitalSource> source,
                         std::function<void(bool, bool)> callback);
@@ -63,7 +79,10 @@ class AsynchronousInterrupt {
    *
    * <p> At construction, the interrupt will trigger on the rising edge.
    *
-   * <p> The first bool in the callback is rising, the 2nd is falling.
+   * @param source the DigitalSource the interrupts are triggered from
+   * @param f the callback function to call when the interrupt is triggered
+   * @param arg the first argument, interrupt was triggered on rising edge
+   * @param args the remaing arguments, interrupt was triggered on falling edge
    */
   template <typename Callable, typename Arg, typename... Args>
   AsynchronousInterrupt(DigitalSource& source, Callable&& f, Arg&& arg,
@@ -77,7 +96,10 @@ class AsynchronousInterrupt {
    *
    * <p> At construction, the interrupt will trigger on the rising edge.
    *
-   * <p> The first bool in the callback is rising, the 2nd is falling.
+   * @param source the DigitalSource the interrupts are triggered from
+   * @param f the callback function to call when the interrupt is triggered
+   * @param arg the first argument, interrupt was triggered on rising edge
+   * @param args the remaing arguments, interrupt was triggered on falling edge
    */
   template <typename Callable, typename Arg, typename... Args>
   AsynchronousInterrupt(DigitalSource* source, Callable&& f, Arg&& arg,
@@ -91,7 +113,10 @@ class AsynchronousInterrupt {
    *
    * <p> At construction, the interrupt will trigger on the rising edge.
    *
-   * <p> The first bool in the callback is rising, the 2nd is falling.
+   * @param source the DigitalSource the interrupts are triggered from
+   * @param f the callback function to call when the interrupt is triggered
+   * @param arg the first argument, interrupt was triggered on rising edge
+   * @param args the remaing arguments, interrupt was triggered on falling edge
    */
   template <typename Callable, typename Arg, typename... Args>
   AsynchronousInterrupt(std::shared_ptr<DigitalSource> source, Callable&& f,
@@ -127,7 +152,7 @@ class AsynchronousInterrupt {
    * <p>This function does not require the interrupt to be enabled to work.
    *
    * <p>This only works if rising edge was configured using SetInterruptEdges.
-   * @return the timestamp in seconds relative to getFPGATime
+   * @return the timestamp in seconds relative to GetFPGATime
    */
   units::second_t GetRisingTimestamp();
 
@@ -137,7 +162,7 @@ class AsynchronousInterrupt {
    * <p>This function does not require the interrupt to be enabled to work.
    *
    * <p>This only works if falling edge was configured using SetInterruptEdges.
-   * @return the timestamp in seconds relative to getFPGATime
+   * @return the timestamp in seconds relative to GetFPGATime
    */
   units::second_t GetFallingTimestamp();
 

wpilibc/src/main/native/include/frc/SynchronousInterrupt.h

@@ -13,7 +13,7 @@ namespace frc {
 class DigitalSource;
 
 /**
- * Class for handling ssynchronous interrupts.
+ * Class for handling synchronous (blocking) interrupts.
  *
  * <p> By default, interrupts will occur on rising edge.
  *
@@ -30,16 +30,22 @@ class SynchronousInterrupt {
 
   /**
    * Construct a Synchronous Interrupt from a Digital Source.
+   *
+   * @param source the DigitalSource the interrupts are triggered from
    */
   explicit SynchronousInterrupt(DigitalSource& source);
 
   /**
    * Construct a Synchronous Interrupt from a Digital Source.
+   *
+   * @param source the DigitalSource the interrupts are triggered from
    */
   explicit SynchronousInterrupt(DigitalSource* source);
 
   /**
    * Construct a Synchronous Interrupt from a Digital Source.
+   *
+   * @param source the DigitalSource the interrupts are triggered from
    */
   explicit SynchronousInterrupt(std::shared_ptr<DigitalSource> source);
 
@@ -72,6 +78,8 @@ class SynchronousInterrupt {
 
   /**
    * Get the timestamp (relative to FPGA Time) of the last rising edge.
+   *
+   * @return the timestamp in seconds relative to getFPGATime
    */
   units::second_t GetRisingTimestamp();
 

wpilibj/src/main/java/edu/wpi/first/wpilibj/AsynchronousInterrupt.java

@@ -10,7 +10,7 @@ import java.util.concurrent.atomic.AtomicBoolean;
 import java.util.function.BiConsumer;
 
 /**
- * Class for handling asynchrounous interrupts.
+ * Class for handling asynchronous interrupts using a callback thread.
  *
  * <p>By default, interrupts will occur on rising edge. Callbacks are disabled by default, and
  * enable() must be called before they will occur.
@@ -18,7 +18,7 @@ import java.util.function.BiConsumer;
  * <p>Both rising and falling edges can be indicated in one callback if both a rising and falling
  * edge occurred since the previous callback.
  *
- * <p>Synchronous interrupts are handled by the SynchronousInterrupt class.
+ * <p>Synchronous (blocking) interrupts are handled by the SynchronousInterrupt class.
  */
 public class AsynchronousInterrupt implements AutoCloseable {
   private final BiConsumer<Boolean, Boolean> m_callback;
@@ -34,6 +34,9 @@ public class AsynchronousInterrupt implements AutoCloseable {
    *
    * <p>Callbacks will not be triggered until enable() is called.
    *
+   * <p>The first bool in the callback indicates the rising edge triggered the interrupt, the second
+   * bool is falling edge.
+   *
    * @param source The digital source to use.
    * @param callback The callback to call on an interrupt
    */

wpilibj/src/main/java/edu/wpi/first/wpilibj/SynchronousInterrupt.java

@@ -9,7 +9,7 @@ import static edu.wpi.first.wpilibj.util.ErrorMessages.requireNonNullParam;
 import edu.wpi.first.hal.InterruptJNI;
 
 /**
- * Class for handling sychronous interrupts.
+ * Class for handling synchronous (blocking) interrupts.
  *
  * <p>By default, interrupts will occur on rising edge.
  *
@@ -36,11 +36,11 @@ public class SynchronousInterrupt implements AutoCloseable {
     }
 
     /**
-     * Create a wait result.
+     * Create a wait result enum.
      *
-     * @param rising True if a rising edge occured.
-     * @param falling True if a falling edge occured.
-     * @return A wait result.
+     * @param rising True if a rising edge occurred.
+     * @param falling True if a falling edge occurred.
+     * @return A wait result enum.
      */
     public static WaitResult getValue(boolean rising, boolean falling) {
       if (rising && falling) {
@@ -83,11 +83,11 @@ public class SynchronousInterrupt implements AutoCloseable {
   /**
    * Wait for interrupt that returns the raw result value from the hardware.
    *
-   * <p>Used by AsynchronousInterrupt. Users prefer to use waitForInterrupt.
+   * <p>Used by AsynchronousInterrupt. Users should use waitForInterrupt.
    *
    * @param timeoutSeconds The timeout in seconds. 0 or less will return immediately.
-   * @param ignorePrevious True to ignore if a previous interrupt has occured, and only wait for a
-   *     new trigger. False will consider if an interrupt has occured since the last time the
+   * @param ignorePrevious True to ignore if a previous interrupt has occurred, and only wait for a
+   *     new trigger. False will consider if an interrupt has occurred since the last time the
    *     interrupt was read.
    * @return The raw hardware interrupt result
    */
@@ -99,10 +99,10 @@ public class SynchronousInterrupt implements AutoCloseable {
    * Wait for an interrupt.
    *
    * @param timeoutSeconds The timeout in seconds. 0 or less will return immediately.
-   * @param ignorePrevious True to ignore if a previous interrupt has occured, and only wait for a
-   *     new trigger. False will consider if an interrupt has occured since the last time the
+   * @param ignorePrevious True to ignore if a previous interrupt has occurred, and only wait for a
+   *     new trigger. False will consider if an interrupt has occurred since the last time the
    *     interrupt was read.
-   * @return Result of which edges were triggered, or if an timeout occured.
+   * @return Result of which edges were triggered, or if an timeout occurred.
    */
   public WaitResult waitForInterrupt(double timeoutSeconds, boolean ignorePrevious) {
     int result = InterruptJNI.waitForInterrupt(m_handle, timeoutSeconds, ignorePrevious);
@@ -117,10 +117,10 @@ public class SynchronousInterrupt implements AutoCloseable {
   }
 
   /**
-   * Wait for an interrupt, ingoring any previously occuring interrupts.
+   * Wait for an interrupt, ignoring any previously occurring interrupts.
    *
    * @param timeoutSeconds The timeout in seconds. 0 or less will return immediately.
-   * @return Result of which edges were triggered, or if an timeout occured.
+   * @return Result of which edges were triggered, or if an timeout occurred.
    */
   public WaitResult waitForInterrupt(double timeoutSeconds) {
     return waitForInterrupt(timeoutSeconds, true);