document more HAL things

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

@@ -4,6 +4,7 @@
 
 package edu.wpi.first.hal;
 
+/** Represents a CAN message read from a stream */
 public class CANStreamMessage {
   /** The message data */
   @SuppressWarnings("MemberName")

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

@@ -371,8 +371,18 @@ public static native int sendError(
    */
   public static native boolean refreshDSData();
 
+  /**
+   * Adds an event handle to be signalled when new data arrives.
+   *
+   * @param handle the event handle to be signalled
+   */
   public static native void provideNewDataEventHandle(int handle);
 
+  /**
+   * Removes the event handle from being singalled when new data arrives.
+   *
+   * @param handle the event handle to remove
+   */
   public static native void removeNewDataEventHandle(int handle);
 
   /**

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

@@ -82,6 +82,7 @@ public final class HAL extends JNIWrapper {
 
   private static final List<Runnable> s_simPeriodicBefore = new ArrayList<>();
 
+  /** A callback to be run by IterativeRobotBase prior to the user's simulationPeriodic code. */
   public static final class SimPeriodicBeforeCallback implements AutoCloseable {
     private SimPeriodicBeforeCallback(Runnable r) {
       m_run = r;
@@ -128,6 +129,7 @@ public static void simPeriodicBefore() {
 
   private static final List<Runnable> s_simPeriodicAfter = new ArrayList<>();
 
+  /** A callback to be run by IterativeRobotBase after the user's simulationPeriodic code. */
   public static final class SimPeriodicAfterCallback implements AutoCloseable {
     private SimPeriodicAfterCallback(Runnable r) {
       m_run = r;

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

@@ -10,17 +10,37 @@
  * @see "hal/HALBase.h"
  */
 public final class HALUtil extends JNIWrapper {
+  /** A pointer parameter to a method is NULL */
   public static final int NULL_PARAMETER = -1005;
+
+  /** Analog module sample rate is too high */
   public static final int SAMPLE_RATE_TOO_HIGH = 1001;
+
+  /** Voltage to convert to raw value is out of range [0; 5] */
   public static final int VOLTAGE_OUT_OF_RANGE = 1002;
+
+  /** Digital module loop timing is not the expected value */
   public static final int LOOP_TIMING_ERROR = 1004;
+
+  /** The operation cannot be completed */
   public static final int INCOMPATIBLE_STATE = 1015;
+
+  /** Attempted to read AnalogTrigger pulse output. */
   public static final int ANALOG_TRIGGER_PULSE_OUTPUT_ERROR = -1011;
+
+  /** No available resources to allocate */
   public static final int NO_AVAILABLE_RESOURCES = -104;
+
+  /** A parameter is out of range. */
   public static final int PARAMETER_OUT_OF_RANGE = -1028;
 
+  /** roboRIO 1.0. */
   public static final int RUNTIME_ROBORIO = 0;
+
+  /** roboRIO 2.0. */
   public static final int RUNTIME_ROBORIO2 = 1;
+
+  /** Simulation runtime. */
   public static final int RUNTIME_SIMULATION = 2;
 
   /**

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

@@ -4,12 +4,24 @@
 
 package edu.wpi.first.hal;
 
+/** Represents a HAL entry value */
 public final class HALValue {
+  /** Unassigned type */
   public static final int kUnassigned = 0;
+
+  /** Boolean */
   public static final int kBoolean = 0x01;
+
+  /** Double */
   public static final int kDouble = 0x02;
+
+  /** Enum */
   public static final int kEnum = 0x04;
+
+  /** Int */
   public static final int kInt = 0x08;
+
+  /** Long */
   public static final int kLong = 0x10;
 
   private int m_type;
@@ -132,6 +144,11 @@ public static HALValue makeDouble(double value) {
     return new HALValue(value, kDouble);
   }
 
+  /**
+   * Build a HAL unassigned value.
+   *
+   * @return HAL value
+   */
   public static HALValue makeUnassigned() {
     return new HALValue();
   }

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

@@ -10,6 +10,7 @@
  * @see "hal/Interrupts.h"
  */
 public class InterruptJNI extends JNIWrapper {
+  /** Invalid handle value */
   public static final int HalInvalidHandle = 0;
 
   /**

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

@@ -63,6 +63,11 @@ public static synchronized void forceLoad() throws IOException {
     libraryLoaded = true;
   }
 
+  /**
+   * Dummy function to suppress unused variable warnings.
+   *
+   * @param object variable to suppress
+   */
   public static void suppressUnused(Object object) {}
 
   /** Utility class. */

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

@@ -4,6 +4,11 @@
 
 package edu.wpi.first.hal;
 
+/**
+ * LED JNI Functions.
+ *
+ * @see "hal/LEDs.h"
+ */
 public class LEDJNI extends JNIWrapper {
   /** LED Off state */
   public static final int RADIO_LED_STATE_OFF = 0;

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

@@ -4,6 +4,11 @@
 
 package edu.wpi.first.hal;
 
+/**
+ * PWM JNI Functions.
+ *
+ * @see "hal/PWM.h"
+ */
 public class PWMJNI extends DIOJNI {
   /**
    * Initializes a PWM port.

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

@@ -12,16 +12,34 @@
  * @see "SPI.h"
  */
 public class SPIJNI extends JNIWrapper {
+  /** Invalid port number */
   public static final int INVALID_PORT = -1;
+
+  /** Onboard SPI bus port CS0. */
   public static final int ONBOARD_CS0_PORT = 0;
+
+  /** Onboard SPI bus port CS1. */
   public static final int ONBOARD_CS1_PORT = 1;
+
+  /** Onboard SPI bus port CS2. */
   public static final int ONBOARD_CS2_PORT = 2;
+
+  /** Onboard SPI bus port CS3. */
   public static final int ONBOARD_CS3_PORT = 3;
+
+  /** MXP (roboRIO MXP) SPI bus port. */
   public static final int MXP_PORT = 4;
 
+  /** Clock idle low, data sampled on rising edge. */
   public static final int SPI_MODE0 = 0;
+
+  /** Clock idle low, data sampled on falling edge. */
   public static final int SPI_MODE1 = 1;
+
+  /** Clock idle high, data sampled on falling edge. */
   public static final int SPI_MODE2 = 2;
+
+  /** Clock idle high, data sampled on rising edge. */
   public static final int SPI_MODE3 = 3;
 
   /**

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

@@ -25,6 +25,7 @@ public enum Direction {
     /** Bidirectional direction for simulation devices. */
     kBidir(SimDeviceJNI.kBidir);
 
+    /** The native value of this Direction */
     public final int m_value;
 
     Direction(int value) {

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

@@ -4,9 +4,19 @@
 
 package edu.wpi.first.hal;
 
+/**
+ * SimDevice JNI Functions.
+ *
+ * @see "hal/SimDevice.h"
+ */
 public class SimDeviceJNI extends JNIWrapper {
+  /** Input direction */
   public static final int kInput = 0;
+
+  /** Output direction */
   public static final int kOutput = 1;
+
+  /** Bidirectional */
   public static final int kBidir = 2;
 
   /**

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

@@ -42,5 +42,6 @@ public void setValue(HALValue value) {
     SimDeviceJNI.setSimValue(m_handle, value);
   }
 
+  /** The native handle for this SimValue */
   protected final int m_handle;
 }

hal/src/main/native/include/hal/DriverStation.h

@@ -219,7 +219,18 @@ int32_t HAL_GetMatchInfo(HAL_MatchInfo* info);
  */
 HAL_Bool HAL_RefreshDSData(void);
 
+/**
+ * Adds an event handle to be signalled when new data arrives.
+ *
+ * @param handle the event handle to be signalled
+ */
 void HAL_ProvideNewDataEventHandle(WPI_EventHandle handle);
+
+/**
+ * Removes the event handle from being singalled when new data arrives.
+ *
+ * @param handle the event handle to remove
+ */
 void HAL_RemoveNewDataEventHandle(WPI_EventHandle handle);
 
 /**

hal/src/main/native/include/hal/HALBase.h

@@ -24,9 +24,15 @@
  * @{
  */
 
+/**
+ * Runtime type.
+ */
 HAL_ENUM(HAL_RuntimeType) {
+  /** roboRIO 1.0 */
   HAL_Runtime_RoboRIO,
+  /** roboRIO 2.0 */
   HAL_Runtime_RoboRIO2,
+  /** Simulation runtime */
   HAL_Runtime_Simulation
 };
 

hal/src/main/native/include/hal/SPITypes.h

@@ -14,19 +14,31 @@
  * @{
  */
 
+/** SPI port. */
 HAL_ENUM(HAL_SPIPort) {
+  /** Invalid port number */
   HAL_SPI_kInvalid = -1,
+  /** Onboard SPI bus port CS0. */
   HAL_SPI_kOnboardCS0,
+  /** Onboard SPI bus port CS1. */
   HAL_SPI_kOnboardCS1,
+  /** Onboard SPI bus port CS2. */
   HAL_SPI_kOnboardCS2,
+  /** Onboard SPI bus port CS3. */
   HAL_SPI_kOnboardCS3,
+  /** MXP (roboRIO MXP) SPI bus port. */
   HAL_SPI_kMXP
 };
 
+/** SPI mode. */
 HAL_ENUM(HAL_SPIMode) {
+  /** Clock idle low, data sampled on rising edge. */
   HAL_SPI_kMode0 = 0,
+  /** Clock idle low, data sampled on falling edge. */
   HAL_SPI_kMode1 = 1,
+  /** Clock idle high, data sampled on falling edge. */
   HAL_SPI_kMode2 = 2,
+  /** Clock idle high, data sampled on rising edge. */
   HAL_SPI_kMode3 = 3,
 };
 

hal/src/main/native/include/hal/Value.h

@@ -8,11 +8,17 @@
 
 /** HAL data types. */
 enum HAL_Type {
+  /** Unassigned type */
   HAL_UNASSIGNED = 0,
+  /** Boolean */
   HAL_BOOLEAN = 0x01,
+  /** Double */
   HAL_DOUBLE = 0x02,
+  /** Enum */
   HAL_ENUM = 0x04,
+  /** Int */
   HAL_INT = 0x08,
+  /** Long */
   HAL_LONG = 0x10,
 };