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.

wpiutil/src/main/java/edu/wpi/first/wpiutil/CircularBuffer.java

@@ -61,6 +61,8 @@ public class CircularBuffer {
   /**
    * Push new value onto front of the buffer. The value at the back is overwritten if the buffer is
    * full.
+   *
+   * @param value The value to push.
    */
   public void addFirst(double value) {
     if (m_data.length == 0) {
@@ -79,6 +81,8 @@ public class CircularBuffer {
   /**
    * Push new value onto back of the buffer. The value at the front is overwritten if the buffer is
    * full.
+   *
+   * @param value The value to push.
    */
   public void addLast(double value) {
     if (m_data.length == 0) {
@@ -112,7 +116,11 @@ public class CircularBuffer {
     return temp;
   }
 
-  /** Pop value at back of buffer. */
+  /**
+   * Pop value at back of buffer.
+   *
+   * @return value at back of buffer
+   */
   public double removeLast() {
     // If there are no elements in the buffer, do nothing
     if (m_length == 0) {
@@ -127,6 +135,8 @@ public class CircularBuffer {
    * Resizes internal buffer to given size.
    *
    * <p>A new buffer is allocated because arrays are not resizable.
+   *
+   * @param size New buffer size.
    */
   void resize(int size) {
     double[] newBuffer = new double[size];
@@ -150,18 +160,27 @@ public class CircularBuffer {
   /**
    * Get the element at the provided index relative to the start of the buffer.
    *
+   * @param index Index into the buffer.
    * @return Element at index starting from front of buffer.
    */
   public double get(int index) {
     return m_data[(m_front + index) % m_data.length];
   }
 
-  /** Increment an index modulo the length of the m_data buffer. */
+  /**
+   * Increment an index modulo the length of the m_data buffer.
+   *
+   * @param index Index into the buffer.
+   */
   private int moduloInc(int index) {
     return (index + 1) % m_data.length;
   }
 
-  /** Decrement an index modulo the length of the m_data buffer. */
+  /**
+   * Decrement an index modulo the length of the m_data buffer.
+   *
+   * @param index Index into the buffer.
+   */
   private int moduloDec(int index) {
     if (index == 0) {
       return m_data.length - 1;

wpiutil/src/main/java/edu/wpi/first/wpiutil/ErrorMessages.java

@@ -17,9 +17,11 @@ public final class ErrorMessages {
    * Requires that a parameter of a method not be null; prints an error message with helpful
    * debugging instructions if the parameter is null.
    *
+   * @param <T> Type of object.
    * @param obj The parameter that must not be null.
    * @param paramName The name of the parameter.
    * @param methodName The name of the method.
+   * @return The object parameter confirmed not to be null.
    */
   public static <T> T requireNonNullParam(T obj, String paramName, String methodName) {
     return requireNonNull(

wpiutil/src/main/java/edu/wpi/first/wpiutil/RuntimeDetector.java

@@ -60,50 +60,77 @@ public final class RuntimeDetector {
     }
   }
 
-  /** Get the file prefix for the current system. */
+  /**
+   * Get the file prefix for the current system.
+   *
+   * @return The file prefix.
+   */
   public static synchronized String getFilePrefix() {
     computePlatform();
 
     return filePrefix;
   }
 
-  /** Get the file extension for the current system. */
+  /**
+   * Get the file extension for the current system.
+   *
+   * @return The file extension.
+   */
   public static synchronized String getFileExtension() {
     computePlatform();
 
     return fileExtension;
   }
 
-  /** Get the platform path for the current system. */
+  /**
+   * Get the platform path for the current system.
+   *
+   * @return The platform path.
+   */
   public static synchronized String getPlatformPath() {
     computePlatform();
 
     return filePath;
   }
 
-  /** Get the path to the requested resource. */
+  /**
+   * Get the path to the requested resource.
+   *
+   * @param libName Library name.
+   * @return The path to the requested resource.
+   */
   public static synchronized String getLibraryResource(String libName) {
     computePlatform();
 
     return filePath + filePrefix + libName + fileExtension;
   }
 
-  /** Get the path to the hash to the requested resource. */
+  /**
+   * Get the path to the hash to the requested resource.
+   *
+   * @param libName Library name.
+   * @return The path to the hash to the requested resource.
+   */
   public static synchronized String getHashLibraryResource(String libName) {
     computePlatform();
 
     return filePath + libName + ".hash";
   }
 
+  /**
+   * Check if hardware platform is Athena.
+   *
+   * @return True if hardware platform is Athena.
+   */
   public static boolean isAthena() {
     File runRobotFile = new File("/usr/local/frc/bin/frcRunRobot.sh");
     return runRobotFile.exists();
   }
 
   /**
-   * check if os is raspbian.
+   * Check if OS is Raspbian.
    *
-   * @return if os is raspbian
+   * @return True if OS is Raspbian.
    */
   public static boolean isRaspbian() {
     try (BufferedReader reader = Files.newBufferedReader(Paths.get("/etc/os-release"))) {

wpiutil/src/main/java/edu/wpi/first/wpiutil/RuntimeLoader.java

@@ -20,7 +20,11 @@ import java.util.Scanner;
 public final class RuntimeLoader<T> {
   private static String defaultExtractionRoot;
 
-  /** Gets the default extration root location (~/.wpilib/nativecache). */
+  /**
+   * Gets the default extration root location (~/.wpilib/nativecache).
+   *
+   * @return The default extraction root location.
+   */
   public static synchronized String getDefaultExtractionRoot() {
     if (defaultExtractionRoot != null) {
       return defaultExtractionRoot;
@@ -37,8 +41,9 @@ public final class RuntimeLoader<T> {
   /**
    * Creates a new library loader.
    *
-   * <p>Resources loaded on disk from extractionRoot, and from classpath from the passed in class.
-   * Library name is the passed in name.
+   * @param libraryName Name of library to load.
+   * @param extractionRoot Location from which to load the library.
+   * @param cls Class whose classpath the given library belongs.
    */
   public RuntimeLoader(String libraryName, String extractionRoot, Class<T> cls) {
     m_libraryName = libraryName;
@@ -46,6 +51,12 @@ public final class RuntimeLoader<T> {
     m_extractionRoot = extractionRoot;
   }
 
+  /**
+   * Returns a load error message given the information in the provided UnsatisfiedLinkError.
+   *
+   * @param ule UnsatisfiedLinkError object.
+   * @return A load error message.
+   */
   private String getLoadErrorMessage(UnsatisfiedLinkError ule) {
     StringBuilder msg = new StringBuilder(512);
     msg.append(m_libraryName)
@@ -64,7 +75,11 @@ public final class RuntimeLoader<T> {
     return msg.toString();
   }
 
-  /** Loads a native library. */
+  /**
+   * Loads a native library.
+   *
+   * @throws IOException if the library fails to load
+   */
   @SuppressWarnings("PMD.PreserveStackTrace")
   public void loadLibrary() throws IOException {
     try {
@@ -106,7 +121,11 @@ public final class RuntimeLoader<T> {
     }
   }
 
-  /** Load a native library by directly hashing the file. */
+  /**
+   * Load a native library by directly hashing the file.
+   *
+   * @throws IOException if the library failed to load
+   */
   @SuppressWarnings({"PMD.PreserveStackTrace", "PMD.EmptyWhileStmt"})
   public void loadLibraryHashed() throws IOException {
     try {

wpiutil/src/main/java/edu/wpi/first/wpiutil/WPIUtilJNI.java

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