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

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);
 }