[docs] Add Missing JNI docs from C++ (NFC) (#6139)

apriltag/src/main/java/edu/wpi/first/apriltag/jni/AprilTagJNI.java

@@ -206,8 +206,22 @@ public class AprilTagJNI {
       double cx,
       double cy);
 
+  /**
+   * Generates a RawFrame containing the apriltag with the id with family 16h5 passed in.
+   *
+   * @param frameObj generated frame (output parameter).
+   * @param frame raw frame handle
+   * @param id id
+   */
   public static native void generate16h5AprilTagImage(RawFrame frameObj, long frame, int id);
 
+  /**
+   * Generates a RawFrame containing the apriltag with the id with family 36h11 passed in.
+   *
+   * @param frameObj generated frame (output parameter).
+   * @param frame raw frame handle
+   * @param id id
+   */
   public static native void generate36h11AprilTagImage(RawFrame frameObj, long frame, int id);
 
   /** Utility class. */

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

@@ -84,6 +84,16 @@ public class AnalogJNI extends JNIWrapper {
    */
   public static native boolean checkAnalogInputChannel(int channel);
 
+  /**
+   * Checks that the analog output channel number is valid.
+   *
+   * <p>Verifies that the analog channel number is one of the legal channel numbers. Channel numbers
+   * are 0-based.
+   *
+   * @param channel The analog output channel number.
+   * @return Analog channel is valid
+   * @see "HAL_CheckAnalogOutputChannel"
+   */
   public static native boolean checkAnalogOutputChannel(int channel);
 
   /**
@@ -95,8 +105,22 @@ public class AnalogJNI extends JNIWrapper {
    */
   public static native void setAnalogInputSimDevice(int handle, int device);
 
+  /**
+   * Sets an analog output value.
+   *
+   * @param portHandle the analog output handle
+   * @param voltage the voltage (0-5v) to output
+   * @see "HAL_SetAnalogOutput"
+   */
   public static native void setAnalogOutput(int portHandle, double voltage);
 
+  /**
+   * Gets the current analog output value.
+   *
+   * @param portHandle the analog output handle
+   * @return the current output voltage (0-5v)
+   * @see "HAL_GetAnalogOutput"
+   */
   public static native double getAnalogOutput(int portHandle);
 
   /**

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

@@ -5,12 +5,41 @@
 package edu.wpi.first.hal;
 
 public class PWMJNI extends DIOJNI {
+  /**
+   * Initializes a PWM port.
+   *
+   * @param halPortHandle the port to initialize
+   * @return the created pwm handle
+   */
   public static native int initializePWMPort(int halPortHandle);
 
+  /**
+   * Checks if a pwm channel is valid.
+   *
+   * @param channel the channel to check
+   * @return true if the channel is valid, otherwise false
+   */
   public static native boolean checkPWMChannel(int channel);
 
+  /**
+   * Frees a PWM port.
+   *
+   * @param pwmPortHandle the pwm handle
+   */
   public static native void freePWMPort(int pwmPortHandle);
 
+  /**
+   * Sets the configuration settings for the PWM channel.
+   *
+   * <p>All values are in microseconds.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @param maxPwm the maximum PWM value
+   * @param deadbandMaxPwm the high range of the center deadband
+   * @param centerPwm the center PWM value
+   * @param deadbandMinPwm the low range of the center deadband
+   * @param minPwm the minimum PWM value
+   */
   public static native void setPWMConfigMicroseconds(
       int pwmPortHandle,
       int maxPwm,
@@ -19,30 +48,120 @@ public class PWMJNI extends DIOJNI {
       int deadbandMinPwm,
       int minPwm);
 
+  /**
+   * Gets the pwm configuration settings for the PWM channel.
+   *
+   * <p>Values are in microseconds.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @return the pwm configuration settings
+   */
   public static native PWMConfigDataResult getPWMConfigMicroseconds(int pwmPortHandle);
 
+  /**
+   * Sets if the FPGA should output the center value if the input value is within the deadband.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @param eliminateDeadband true to eliminate deadband, otherwise false
+   */
   public static native void setPWMEliminateDeadband(int pwmPortHandle, boolean eliminateDeadband);
 
+  /**
+   * Gets the current eliminate deadband value.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @return true if set, otherwise false
+   */
   public static native boolean getPWMEliminateDeadband(int pwmPortHandle);
 
+  /**
+   * Sets a PWM channel to the desired pulse width in microseconds.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @param microsecondPulseTime the PWM value to set
+   */
   public static native void setPulseTimeMicroseconds(int pwmPortHandle, int microsecondPulseTime);
 
+  /**
+   * Sets a PWM channel to the desired scaled value.
+   *
+   * <p>The values range from -1 to 1 and the period is controlled by the PWM Period and MinHigh
+   * registers.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @param speed the scaled PWM value to set
+   */
   public static native void setPWMSpeed(int pwmPortHandle, double speed);
 
+  /**
+   * Sets a PWM channel to the desired position value.
+   *
+   * <p>The values range from 0 to 1 and the period is controlled by the PWM Period and MinHigh
+   * registers.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @param position the positional PWM value to set
+   */
   public static native void setPWMPosition(int pwmPortHandle, double position);
 
+  /**
+   * Gets the current microsecond pulse time from a PWM channel.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @return the current PWM microsecond pulse time
+   */
   public static native int getPulseTimeMicroseconds(int pwmPortHandle);
 
+  /**
+   * Gets a scaled value from a PWM channel.
+   *
+   * <p>The values range from -1 to 1.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @return the current speed PWM value
+   */
   public static native double getPWMSpeed(int pwmPortHandle);
 
+  /**
+   * Gets a position value from a PWM channel.
+   *
+   * <p>The values range from 0 to 1.
+   *
+   * @param pwmPortHandle the PWM handle
+   * @return the current positional PWM value
+   */
   public static native double getPWMPosition(int pwmPortHandle);
 
+  /**
+   * Sets a PWM channel to be disabled.
+   *
+   * <p>The channel is disabled until the next time it is set. Note this is different from just
+   * setting a 0 speed, as this will actively stop all signaling on the channel.
+   *
+   * @param pwmPortHandle the PWM handle.
+   */
   public static native void setPWMDisabled(int pwmPortHandle);
 
+  /**
+   * Forces a PWM signal to go to 0 temporarily.
+   *
+   * @param pwmPortHandle the PWM handle.
+   */
   public static native void latchPWMZero(int pwmPortHandle);
 
+  /**
+   * Sets the PWM output to be a continuous high signal while enabled.
+   *
+   * @param pwmPortHandle the PWM handle.
+   */
   public static native void setAlwaysHighMode(int pwmPortHandle);
 
+  /**
+   * Sets how how often the PWM signal is squelched, thus scaling the period.
+   *
+   * @param pwmPortHandle the PWM handle.
+   * @param squelchMask the 2-bit mask of outputs to squelch
+   */
   public static native void setPWMPeriodScale(int pwmPortHandle, int squelchMask);
 
   /** Utility class. */

wpinet/src/main/java/edu/wpi/first/net/WPINetJNI.java

@@ -69,8 +69,21 @@ public class WPINetJNI {
     libraryLoaded = true;
   }
 
+  /**
+   * Forward a local TCP port to a remote host and port. Note that local ports less than 1024 won't
+   * work as a normal user.
+   *
+   * @param port local port number
+   * @param remoteHost remote IP address / DNS name
+   * @param remotePort remote port number
+   */
   public static native void addPortForwarder(int port, String remoteHost, int remotePort);
 
+  /**
+   * Stop TCP forwarding on a port.
+   *
+   * @param port local port number
+   */
   public static native void removePortForwarder(int port);
 
   public static native int createMulticastServiceAnnouncer(

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

@@ -82,18 +82,67 @@ public class WPIUtilJNI {
 
   public static native long getSystemTime();
 
+  /**
+   * Creates an event. Events have binary state (signaled or not signaled) and may be either
+   * automatically reset or manually reset. Automatic-reset events go to non-signaled state when a
+   * WaitForObject is woken up by the event; manual-reset events require ResetEvent() to be called
+   * to set the event to non-signaled state; if ResetEvent() is not called, any waiter on that event
+   * will immediately wake when called.
+   *
+   * @param manualReset true for manual reset, false for automatic reset
+   * @param initialState true to make the event initially in signaled state
+   * @return Event handle
+   */
   public static native int createEvent(boolean manualReset, boolean initialState);
 
+  /**
+   * Destroys an event. Destruction wakes up any waiters.
+   *
+   * @param eventHandle event handle
+   */
   public static native void destroyEvent(int eventHandle);
 
+  /**
+   * Sets an event to signaled state.
+   *
+   * @param eventHandle event handle
+   */
   public static native void setEvent(int eventHandle);
 
+  /**
+   * Sets an event to non-signaled state.
+   *
+   * @param eventHandle event handle
+   */
   public static native void resetEvent(int eventHandle);
 
+  /**
+   * Creates a semaphore. Semaphores keep an internal counter. Releasing the semaphore increases the
+   * count. A semaphore with a non-zero count is considered signaled. When a waiter wakes up it
+   * atomically decrements the count by 1. This is generally useful in a single-supplier,
+   * multiple-consumer scenario.
+   *
+   * @param initialCount initial value for the semaphore's internal counter
+   * @param maximumCount maximum value for the samephore's internal counter
+   * @return Semaphore handle
+   */
   public static native int createSemaphore(int initialCount, int maximumCount);
 
+  /**
+   * Destroys a semaphore. Destruction wakes up any waiters.
+   *
+   * @param semHandle semaphore handle
+   */
   public static native void destroySemaphore(int semHandle);
 
+  /**
+   * Releases N counts of a semaphore.
+   *
+   * @param semHandle semaphore handle
+   * @param releaseCount amount to add to semaphore's internal counter; must be positive
+   * @return True on successful release, false on failure (e.g. release count would exceed maximum
+   *     value, or handle invalid)
+   */
   public static native boolean releaseSemaphore(int semHandle, int releaseCount);
 
   static native long allocateRawFrame();

wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLogJNI.java

@@ -13,34 +13,139 @@ import java.nio.ByteBuffer;
  * @see "wpiutil/DataLog.h"
  */
 public class DataLogJNI extends WPIUtilJNI {
+  /**
+   * Create a new Data Log. The log will be initially created with a temporary filename.
+   *
+   * @param dir directory to store the log
+   * @param filename filename to use; if none provided, a random filename is generated of the form
+   *     "wpilog_{}.wpilog"
+   * @param period time between automatic flushes to disk, in seconds; this is a time/storage
+   *     tradeoff
+   * @param extraHeader extra header data
+   * @return data log implementation handle
+   */
   static native long create(String dir, String filename, double period, String extraHeader);
 
+  /**
+   * Change log filename.
+   *
+   * @param impl data log implementation handle
+   * @param filename filename
+   */
   static native void setFilename(long impl, String filename);
 
+  /**
+   * Explicitly flushes the log data to disk.
+   *
+   * @param impl data log implementation handle
+   */
   static native void flush(long impl);
 
+  /**
+   * Pauses appending of data records to the log. While paused, no data records are saved (e.g.
+   * AppendX is a no-op). Has no effect on entry starts / finishes / metadata changes.
+   *
+   * @param impl data log implementation handle
+   */
   static native void pause(long impl);
 
+  /**
+   * Resumes appending of data records to the log. If called after Stop(), opens a new file (with
+   * random name if SetFilename was not called after Stop()) and appends Start records and schema
+   * data values for all previously started entries and schemas.
+   *
+   * @param impl data log implementation handle
+   */
   static native void resume(long impl);
 
+  /**
+   * Stops appending all records to the log, and closes the log file.
+   *
+   * @param impl data log implementation handle
+   */
   static native void stop(long impl);
 
+  /**
+   * Registers a data schema. Data schemas provide information for how a certain data type string
+   * can be decoded. The type string of a data schema indicates the type of the schema itself (e.g.
+   * "protobuf" for protobuf schemas, "struct" for struct schemas, etc). In the data log, schemas
+   * are saved just like normal records, with the name being generated from the provided name:
+   * "/.schema/<name>". Duplicate calls to this function with the same name are silently
+   * ignored.
+   *
+   * @param impl data log implementation handle
+   * @param name Name (the string passed as the data type for records using this schema)
+   * @param type Type of schema (e.g. "protobuf", "struct", etc)
+   * @param schema Schema data
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void addSchema(long impl, String name, String type, byte[] schema, long timestamp);
 
   static native void addSchemaString(
       long impl, String name, String type, String schema, long timestamp);
 
+  /**
+   * Start an entry. Duplicate names are allowed (with the same type), and result in the same index
+   * being returned (Start/Finish are reference counted). A duplicate name with a different type
+   * will result in an error message being printed to the console and 0 being returned (which will
+   * be ignored by the Append functions).
+   *
+   * @param impl data log implementation handle
+   * @param name Name
+   * @param type Data type
+   * @param metadata Initial metadata (e.g. data properties)
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   * @return Entry index
+   */
   static native int start(long impl, String name, String type, String metadata, long timestamp);
 
+  /**
+   * Finish an entry.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void finish(long impl, int entry, long timestamp);
 
+  /**
+   * Updates the metadata for an entry.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index
+   * @param metadata New metadata for the entry
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void setMetadata(long impl, int entry, String metadata, long timestamp);
 
+  /**
+   * Closes the data log implementation handle.
+   *
+   * @param impl data log implementation handle
+   */
   static native void close(long impl);
 
+  /**
+   * Appends a raw record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by WPI_DataLog_Start()
+   * @param data Byte array to record
+   * @param len Length of byte array
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendRaw(
       long impl, int entry, byte[] data, int start, int len, long timestamp);
 
+  /**
+   * Appends a raw record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by WPI_DataLog_Start()
+   * @param data ByteBuffer to record
+   * @param len Length of byte array
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static void appendRaw(long impl, int entry, ByteBuffer data, int start, int len, long timestamp) {
     if (data.isDirect()) {
       if (start < 0) {
@@ -63,23 +168,103 @@ public class DataLogJNI extends WPIUtilJNI {
   private static native void appendRawBuffer(
       long impl, int entry, ByteBuffer data, int start, int len, long timestamp);
 
+  /**
+   * Appends a boolean record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param value Boolean value to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendBoolean(long impl, int entry, boolean value, long timestamp);
 
+  /**
+   * Appends an integer record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param value Integer value to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendInteger(long impl, int entry, long value, long timestamp);
 
+  /**
+   * Appends a float record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param value Float value to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendFloat(long impl, int entry, float value, long timestamp);
 
+  /**
+   * Appends a double record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param value Double value to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendDouble(long impl, int entry, double value, long timestamp);
 
+  /**
+   * Appends a string record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param value String value to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendString(long impl, int entry, String value, long timestamp);
 
+  /**
+   * Appends a boolean array record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param arr Boolean array to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendBooleanArray(long impl, int entry, boolean[] value, long timestamp);
 
+  /**
+   * Appends an integer array record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param arr Integer array to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendIntegerArray(long impl, int entry, long[] value, long timestamp);
 
+  /**
+   * Appends a float array record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param arr Float array to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendFloatArray(long impl, int entry, float[] value, long timestamp);
 
+  /**
+   * Appends a double array record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param arr Double array to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendDoubleArray(long impl, int entry, double[] value, long timestamp);
 
+  /**
+   * Appends a string array record to the log.
+   *
+   * @param impl data log implementation handle
+   * @param entry Entry index, as returned by Start()
+   * @param arr String array to record
+   * @param timestamp Time stamp (may be 0 to indicate now)
+   */
   static native void appendStringArray(long impl, int entry, String[] value, long timestamp);
 }