HAL: Add Doxygen module documentation (#1246)

This helps organize the functions in the generated docs.

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

@@ -9,6 +9,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_accelerometer Accelerometer Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 /**
  * The acceptable accelerometer ranges.
@@ -69,4 +75,5 @@ double HAL_GetAccelerometerY(void);
 double HAL_GetAccelerometerZ(void);
 #ifdef __cplusplus
 }  // extern "C"
+/** @} */
 #endif

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_analogaccumulator Analog Accumulator Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -106,3 +112,4 @@ void HAL_GetAccumulatorOutput(HAL_AnalogInputHandle analogPortHandle,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_analoggyro Analog Gyro Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -129,3 +135,4 @@ int32_t HAL_GetAnalogGyroCenter(HAL_GyroHandle handle, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_analoginput Analog Input Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -221,3 +227,4 @@ int32_t HAL_GetAnalogOffset(HAL_AnalogInputHandle analogPortHandle,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_analogoutput Analog Output Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -61,3 +67,4 @@ HAL_Bool HAL_CheckAnalogOutputChannel(int32_t channel);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_analogtrigger Analog Trigger Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 /**
  * The type of analog trigger to trigger on.
@@ -134,3 +140,4 @@ HAL_Bool HAL_GetAnalogTriggerOutput(HAL_AnalogTriggerHandle analogTriggerHandle,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_canstream CAN Stream Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // These are copies of defines located in CANSessionMux.h prepended with HAL_
 
 #define HAL_CAN_SEND_PERIOD_NO_REPEAT 0
@@ -115,3 +121,4 @@ void HAL_CAN_GetCANStatus(float* percentBusUtilization, uint32_t* busOffCount,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_canapi CAN API Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 /**
  * The CAN device type.
@@ -189,3 +195,4 @@ void HAL_ReadCANPeriodicPacket(HAL_CANHandle handle, int32_t apiId,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_compressor Compressor Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -134,3 +140,4 @@ HAL_Bool HAL_GetCompressorNotConnectedFault(
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -9,6 +9,12 @@
 
 #include <stdint.h>
 
+/**
+ * @defgroup hal_constants Constants Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -22,3 +28,4 @@ int32_t HAL_GetSystemClockTicksPerMicrosecond(void);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -12,6 +12,12 @@
 #include "hal/AnalogTrigger.h"
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_counter Counter Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 /**
  * The counter mode.
@@ -298,3 +304,4 @@ void HAL_SetCounterReverseDirection(HAL_CounterHandle counterHandle,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_dio DIO Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -191,3 +197,4 @@ int64_t HAL_GetFilterPeriod(int32_t filterIndex, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_driverstation Driver Station Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #define HAL_IO_CONFIG_DATA_SIZE 32
 #define HAL_SYS_STATUS_DATA_SIZE 44
 #define HAL_USER_STATUS_DATA_SIZE \
@@ -357,3 +363,4 @@ void HAL_ObserveUserProgramTest(void);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -12,6 +12,12 @@
 #include "hal/AnalogTrigger.h"
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_encoder Encoder Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 /**
  * The type of index pulse for the encoder.
@@ -292,3 +298,4 @@ HAL_EncoderEncodingType HAL_GetEncoderEncodingType(
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -7,6 +7,12 @@
 
 #pragma once
 
+/**
+ * @defgroup hal_errors Error Defines
+ * @ingroup hal_capi
+ * @{
+ */
+
 #define CTR_RxTimeout_MESSAGE "CTRE CAN Receive Timeout"
 #define CTR_TxTimeout_MESSAGE "CTRE CAN Transmit Timeout"
 #define CTR_InvalidParamValue_MESSAGE "CTRE CAN Invalid Parameter"
@@ -118,3 +124,4 @@
 #define VI_ERROR_ASRL_OVERRUN_MESSAGE "HAL - VISA: Buffer Overrun Error"
 #define VI_ERROR_RSRC_BUSY_MESSAGE "HAL - VISA: Resource Busy"
 #define VI_ERROR_INV_PARAMETER_MESSAGE "HAL - VISA: Invalid Parameter"
+/** @} */

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

@@ -8,14 +8,18 @@
 #pragma once
 
 /**
- * HAL Simulator Extensions are libraries that provide additional simulator
- * functionality, such as a Gazebo interface, or a more light weight simulation.
+ * @defgroup hal_extensions Simulator Extensions
+ * @ingroup hal_capi
+ * HAL Simulator Extensions.  These are libraries that provide additional
+ * simulator functionality, such as a Gazebo interface, or a more light weight
+ * simulation.
  *
  * An extension must expose the HALSIM_InitExtension entry point which is
  * invoked after the library is loaded.
  *
  * The entry point is expected to return < 0 for errors that should stop
  * the HAL completely, 0 for success, and > 0 for a non fatal error.
+ * @{
  */
 typedef int halsim_extension_init_func_t(void);
 
@@ -38,3 +42,4 @@ int HAL_LoadOneExtension(const char* library);
  */
 int HAL_LoadExtensions(void);
 }  // extern "C"
+/** @} */

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

@@ -46,6 +46,12 @@
 namespace HALUsageReporting = nUsageReporting;
 #endif
 
+/**
+ * @defgroup hal_capi WPILib HAL API
+ * Hardware Abstraction Layer to hardware or simulator
+ * @{
+ */
+
 // clang-format off
 HAL_ENUM(HAL_RuntimeType) { HAL_Athena, HAL_Mock };
 // clang-format on
@@ -208,3 +214,4 @@ int64_t HAL_Report(int32_t resource, int32_t instanceNumber, int32_t context,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_i2c I2C Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 HAL_ENUM(HAL_I2CPort) { HAL_I2C_kOnboard = 0, HAL_I2C_kMXP };
 // clang-format on
@@ -87,3 +93,4 @@ void HAL_CloseI2C(HAL_I2CPort port);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -12,6 +12,12 @@
 #include "hal/AnalogTrigger.h"
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_interrupts Interrupts Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -146,3 +152,4 @@ void HAL_SetInterruptUpSourceEdge(HAL_InterruptHandle interruptHandle,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_notifier Notifier Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -79,3 +85,4 @@ uint64_t HAL_WaitForNotifierAlarm(HAL_NotifierHandle notifierHandle,
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,13 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_pdp PDP Functions
+ * @ingroup hal_capi
+ * Functions to control the Power Distribution Panel.
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -112,3 +119,4 @@ void HAL_ClearPDPStickyFaults(HAL_PDPHandle handle, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_pwm PWM Output Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -224,3 +230,4 @@ uint64_t HAL_GetPWMCycleStartTime(int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -9,6 +9,12 @@
 
 #include <stdint.h>
 
+/**
+ * @defgroup hal_ports Ports Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -141,3 +147,4 @@ int32_t HAL_GetNumPDPChannels(void);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_power Power Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -115,3 +121,4 @@ int32_t HAL_GetUserCurrentFaults3V3(int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_relay Relay Output Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -62,3 +68,4 @@ HAL_Bool HAL_GetRelay(HAL_RelayHandle relayPortHandle, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -12,6 +12,12 @@
 #include "hal/AnalogTrigger.h"
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_spi SPI Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 HAL_ENUM(HAL_SPIPort) {
   HAL_SPI_kOnboardCS0 = 0,
@@ -246,3 +252,4 @@ int32_t HAL_GetSPIAutoDroppedCount(HAL_SPIPort port, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_serialport Serial Port Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 // clang-format off
 HAL_ENUM(HAL_SerialPort) {
   HAL_SerialPort_Onboard = 0,
@@ -221,3 +227,4 @@ void HAL_CloseSerial(HAL_SerialPort port, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -11,6 +11,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_solenoid Solenoid Output Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -132,3 +138,4 @@ void HAL_FireOneShot(HAL_SolenoidHandle solenoidPortHandle, int32_t* status);
 #ifdef __cplusplus
 }  // extern "C"
 #endif
+/** @} */

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

@@ -17,6 +17,12 @@
 
 #include "hal/Types.h"
 
+/**
+ * @defgroup hal_threads Threads Functions
+ * @ingroup hal_capi
+ * @{
+ */
+
 extern "C" {
 /**
  * Gets the thread priority for the specified thread.
@@ -69,3 +75,4 @@ HAL_Bool HAL_SetThreadPriority(NativeThreadHandle handle, HAL_Bool realTime,
 HAL_Bool HAL_SetCurrentThreadPriority(HAL_Bool realTime, int32_t priority,
                                       int32_t* status);
 }  // extern "C"
+/** @} */

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

@@ -9,6 +9,12 @@
 
 #include <stdint.h>
 
+/**
+ * @defgroup hal_types Type Definitions
+ * @ingroup hal_capi
+ * @{
+ */
+
 #define HAL_kInvalidHandle 0
 
 typedef int32_t HAL_Handle;
@@ -56,3 +62,4 @@ typedef int32_t HAL_Bool;
   typedef int32_t name; \
   enum name
 #endif
+/** @} */