From faa29d596c9a01447a36fd5eaa18e8ad28434ad4 Mon Sep 17 00:00:00 2001
From: Tyler Veness <calcmogul@gmail.com>
Date: Fri, 1 Jul 2022 06:45:00 -0700
Subject: [PATCH] [wpilib] Improve Notifier docs (NFC) (#4326)

---
 wpilibc/src/main/native/include/frc/Notifier.h         | 10 ++++++++++
 .../src/main/java/edu/wpi/first/wpilibj/Notifier.java  |  9 +++++++++
 2 files changed, 19 insertions(+)

diff --git a/wpilibc/src/main/native/include/frc/Notifier.h b/wpilibc/src/main/native/include/frc/Notifier.h
index 61b7fbbb3c..bda685c928 100644
--- a/wpilibc/src/main/native/include/frc/Notifier.h
+++ b/wpilibc/src/main/native/include/frc/Notifier.h
@@ -19,6 +19,13 @@
 
 namespace frc {
 
+/**
+ * Notifiers run a callback function on a separate thread at a specified period.
+ *
+ * If StartSingle() is used, the callback will run once. If StartPeriodic() is
+ * used, the callback will run repeatedly with the given period until stop() is
+ * called.
+ */
 class Notifier {
  public:
   /**
@@ -95,6 +102,9 @@ class Notifier {
    * interrupt occurs, the event will be immediately requeued for the same time
    * interval.
    *
+   * The user-provided callback should be written in a nonblocking manner so the
+   * callback can be recalled at the next periodic event notification.
+   *
    * @param period Period to call the handler starting one period
    *               after the call to this method.
    */
diff --git a/wpilibj/src/main/java/edu/wpi/first/wpilibj/Notifier.java b/wpilibj/src/main/java/edu/wpi/first/wpilibj/Notifier.java
index 57a346593f..7f8f6069e8 100644
--- a/wpilibj/src/main/java/edu/wpi/first/wpilibj/Notifier.java
+++ b/wpilibj/src/main/java/edu/wpi/first/wpilibj/Notifier.java
@@ -10,6 +10,12 @@ import edu.wpi.first.hal.NotifierJNI;
 import java.util.concurrent.atomic.AtomicInteger;
 import java.util.concurrent.locks.ReentrantLock;
 
+/**
+ * Notifiers run a callback function on a separate thread at a specified period.
+ *
+ * <p>If startSingle() is used, the callback will run once. If startPeriodic() is used, the callback
+ * will run repeatedly with the given period until stop() is called.
+ */
 public class Notifier implements AutoCloseable {
   // The thread waiting on the HAL alarm.
   private Thread m_thread;
@@ -178,6 +184,9 @@ public class Notifier implements AutoCloseable {
    * notification. Each time the interrupt occurs, the event will be immediately requeued for the
    * same time interval.
    *
+   * <p>The user-provided callback should be written in a nonblocking manner so the callback can be
+   * recalled at the next periodic event notification.
+   *
    * @param periodSeconds Period in seconds to call the handler starting one period after the call
    *     to this method.
    */