Fix documentation warnings generated by JavaDoc (NFC) (#3428)

Some C++ Doxygen comments were updated to reflect any wording changes.

See `rg "(@return|@param \w+) TODO" | less` for list of incomplete docs.

hal/src/main/java/edu/wpi/first/hal/AccumulatorResult.java

@@ -13,7 +13,12 @@ public class AccumulatorResult {
   @SuppressWarnings("MemberName")
   public long count;
 
-  /** Set the value and count. */
+  /**
+   * Set the value and count.
+   *
+   * @param value The total value accumulated.
+   * @param count The number of samples accumulated.
+   */
   public void set(long value, long count) {
     this.value = value;
     this.count = count;

hal/src/main/java/edu/wpi/first/hal/CANData.java

@@ -14,7 +14,13 @@ public class CANData {
   @SuppressWarnings("MemberName")
   public long timestamp;
 
-  /** API used from JNI to set the data. */
+  /**
+   * API used from JNI to set the data.
+   *
+   * @param length Length of packet in bytes.
+   * @param timestamp CAN frame timestamp in microseconds.
+   * @return Buffer containing CAN frame.
+   */
   @SuppressWarnings("PMD.MethodReturnsInternalArray")
   public byte[] setData(int length, long timestamp) {
     this.length = length;

hal/src/main/java/edu/wpi/first/hal/HAL.java

@@ -136,17 +136,18 @@ public final class HAL extends JNIWrapper {
   }
 
   /**
-   * Report the usage of a resource of interest. <br>
+   * Report the usage of a resource of interest.
    *
    * <p>Original signature: <code>uint32_t report(tResourceType, uint8_t, uint8_t, const
    * char*)</code>
    *
-   * @param resource one of the values in the tResourceType above (max value 51). <br>
-   * @param instanceNumber an index that identifies the resource instance. <br>
+   * @param resource one of the values in the tResourceType above (max value 51).
+   * @param instanceNumber an index that identifies the resource instance.
    * @param context an optional additional context number for some cases (such as module number).
-   *     Set to 0 to omit. <br>
+   *     Set to 0 to omit.
    * @param feature a string to be included describing features in use on a specific resource.
    *     Setting the same resource more than once allows you to change the feature string.
+   * @return TODO
    */
   public static native int report(int resource, int instanceNumber, int context, String feature);
 

hal/src/main/java/edu/wpi/first/hal/JNIWrapper.java

@@ -40,7 +40,11 @@ public class JNIWrapper {
     }
   }
 
-  /** Force load the library. */
+  /**
+   * Force load the library.
+   *
+   * @throws IOException if the library load failed
+   */
   public static synchronized void forceLoad() throws IOException {
     if (libraryLoaded) {
       return;

hal/src/main/java/edu/wpi/first/hal/MatchInfoData.java

@@ -26,7 +26,15 @@ public class MatchInfoData {
   @SuppressWarnings("MemberName")
   public int matchType;
 
-  /** Called from JNI to set the structure data. */
+  /**
+   * Called from JNI to set the structure data.
+   *
+   * @param eventName Event name.
+   * @param gameSpecificMessage Game-specific message.
+   * @param matchNumber Match number.
+   * @param replayNumber Replay number.
+   * @param matchType Match type.
+   */
   @SuppressWarnings("MissingJavadocMethod")
   public void setData(
       String eventName,

hal/src/main/java/edu/wpi/first/hal/NotifierJNI.java

@@ -11,33 +11,65 @@ package edu.wpi.first.hal;
  * class, which corresponds to the C++ Notifier class, should be used.
  */
 public class NotifierJNI extends JNIWrapper {
-  /** Initializes the notifier. */
+  /**
+   * Initializes the notifier.
+   *
+   * @return True on success.
+   */
   public static native int initializeNotifier();
 
-  /** Sets the HAL notifier thread priority. */
+  /**
+   * Sets the HAL notifier thread priority.
+   *
+   * @param realTime Set to true to set a real-time priority, false for standard priority.
+   * @param priority Priority to set the thread to. For real-time, this is 1-99 with 99 being
+   *     highest. For non-real-time, this is forced to 0. See "man 7 sched" for more details.
+   * @return True on success.
+   */
   public static native boolean setHALThreadPriority(boolean realTime, int priority);
 
-  /** Sets the name of the notifier. */
+  /**
+   * Sets the name of the notifier.
+   *
+   * @param notifierHandle Notifier handle.
+   * @param name Notifier name.
+   */
   public static native void setNotifierName(int notifierHandle, String name);
 
   /**
    * Wakes up the waiter with time=0. Note: after this function is called, all calls to
    * waitForNotifierAlarm() will immediately start returning 0.
+   *
+   * @param notifierHandle Notifier handle.
    */
   public static native void stopNotifier(int notifierHandle);
 
-  /** Deletes the notifier object when we are done with it. */
+  /**
+   * Deletes the notifier object when we are done with it.
+   *
+   * @param notifierHandle Notifier handle.
+   */
   public static native void cleanNotifier(int notifierHandle);
 
-  /** Sets the notifier to wakeup the waiter in another triggerTime microseconds. */
+  /**
+   * Sets the notifier to wakeup the waiter in another triggerTime microseconds.
+   *
+   * @param notifierHandle Notifier handle.
+   * @param triggerTime Trigger time in microseconds.
+   */
   public static native void updateNotifierAlarm(int notifierHandle, long triggerTime);
 
-  /** Cancels any pending wakeups set by updateNotifierAlarm(). Does NOT wake up any waiters. */
+  /**
+   * Cancels any pending wakeups set by updateNotifierAlarm(). Does NOT wake up any waiters.
+   *
+   * @param notifierHandle Notifier handle.
+   */
   public static native void cancelNotifierAlarm(int notifierHandle);
 
   /**
    * Block until woken up by an alarm (or stop).
    *
+   * @param notifierHandle Notifier handle.
    * @return Time when woken up.
    */
   public static native long waitForNotifierAlarm(int notifierHandle);

hal/src/main/java/edu/wpi/first/hal/simulation/SimDeviceDataJNI.java

@@ -61,6 +61,7 @@ public class SimDeviceDataJNI extends JNIWrapper {
    * @param handle simulated value handle
    * @param callback callback
    * @param initialNotify ignored (present for consistency)
+   * @return TODO
    */
   public static native int registerSimValueResetCallback(
       int handle, SimValueCallback callback, boolean initialNotify);