Add doxygen docs for public headers

Added docs for errors, gpio and the client

BUG: 27482120
TEST: Generated a devsite.

Change-Id: I514c75f6c7e8024996025cb10e0ae0860fc456f5

3 files changed, 93 insertions, 113 deletions

diff --git a/include/peripheralmanager/errors.h b/include/peripheralmanager/errors.h
index d0019ce..e57026b 100644
--- a/include/peripheralmanager/errors.h
+++ b/include/peripheralmanager/errors.h
@@ -19,12 +19,19 @@
 
 #include <sys/cdefs.h>
 
+/// @defgroup Errors Peripheral IO Errors
+/// @brief Error Codes
+/// @{
+
+/// Peripherial IO common error codes
 enum peripheral_error_t {
-  PERIPHERAL_IO_OK,
-  PERIPHERAL_IO_UNKNOWN_DEVICE,
-  PERIPHERAL_IO_DEVICE_IN_USE,
-  PERIPHERAL_IO_FUNCTION_NOT_IMPLEMENTED,
-  PERIPHERAL_IO_UNKNOWN_ERROR,
+  PERIPHERAL_IO_OK,  /**<  Ok */
+  PERIPHERAL_IO_UNKNOWN_DEVICE,   /**<  Unknown device */
+  PERIPHERAL_IO_DEVICE_IN_USE,   /**<  Device in use */
+  PERIPHERAL_IO_FUNCTION_NOT_IMPLEMENTED,   /**<  Function not supported on device. */
+  PERIPHERAL_IO_UNKNOWN_ERROR,  /**<  Generic error */
 };
 
+/// @}
+
 #endif  // SYSTEM_PERIPHERALMANAGER_ERRORS_H_
diff --git a/include/peripheralmanager/gpio.h b/include/peripheralmanager/gpio.h
index dbe06a3..28989ea 100644
--- a/include/peripheralmanager/gpio.h
+++ b/include/peripheralmanager/gpio.h
@@ -22,101 +22,81 @@
 
 __BEGIN_DECLS
 
-// Edge trigger types.
+/// @defgroup Gpio Gpio Interface
+/// @brief Functions to control gpio pins.
+///
+/// These functions can be used to control gpio.
+/// @{
+
+/// Edge trigger types.
 enum {
-  NONE_EDGE,
-  RISING_EDGE,
-  FALLING_EDGE,
-  BOTH_EDGE,
+  NONE_EDGE,  /**<  None */
+  RISING_EDGE,  /**<  Rising edge */
+  FALLING_EDGE,  /**<  Falling edge */
+  BOTH_EDGE,  /**<  Both edges */
 };
 
-// GPIO direction types.
+/// GPIO direction types.
 enum {
-  DIRECTION_IN,
-  DIRECTION_OUT_INITIALLY_HIGH,
-  DIRECTION_OUT_INITIALLY_LOW,
+  DIRECTION_IN,  /**<  Input mode */
+  DIRECTION_OUT_INITIALLY_HIGH,  /**<  Output mode, initially set to high */
+  DIRECTION_OUT_INITIALLY_LOW,  /**<  Output mode, initially set to low */
 };
 
-// Possible active types.
+/// Possible active types.
 enum {
-  ACTIVE_LOW,
-  ACTIVE_HIGH,
+  ACTIVE_LOW,  /**<  Active Low */
+  ACTIVE_HIGH,  /**<  Active High */
 };
 
 typedef struct BGpio BGpio;
 
-// Sets the GPIO direction to output.
-//
-// The physical initial value may be different from the logical value based
-// on the active low status
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
-//    direction: One of DIRECTION_IN, DIRECTION_OUT_INITIALLY_HIGH,
-//        DIRECTION_OUT_INITIALLY_LOW.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+
+
+/// Sets the GPIO direction to output.
+/// @param gpio Pointer to the BGpio struct
+/// @param direction One of DIRECTION_IN,
+/// DIRECTION_OUT_INITIALLY_HIGH, DIRECTION_OUT_INITIALLY_LOW.
+/// @return Error code
 int BGpio_setDirection(const BGpio* gpio, int direction);
 
-// Sets the interrupt edge trigger type.
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
-//    type: One of NONE_EDGE, RISING_EDGE, FALLING_EDGE or BOTH_EDGE.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+/// Sets the interrupt edge trigger type.
+/// @param gpio Pointer to the BGpio struct
+/// @param type One of NONE_EDGE, RISING_EDGE, FALLING_EDGE or BOTH_EDGE.
+/// @return Error code
 int BGpio_setEdgeTriggerType(const BGpio* gpio, int type);
 
-// Sets the GPIO’s active low/high status.
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
-//    type: One of ACTIVE_HIGH, ACTIVE_LOW.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+/// Sets the GPIO’s active low/high status.
+/// @param gpio Pointer to the BGpio struct.
+/// @param type One of ACTIVE_HIGH, ACTIVE_LOW.
+/// @return Error code
 int BGpio_setActiveType(const BGpio* gpio, int type);
 
-// Sets the GPIO value (for output GPIO only).
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
-//    value: Value to set.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+/// Sets the GPIO value (for output GPIO only).
+/// @param gpio Pointer to the BGpio struct.
+/// @param value Value to set.
+/// return Error code
 int BGpio_setValue(const BGpio* gpio, int value);
 
-// Gets the GPIO value (for input GPIO only).
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
-//    value: Output pointer to the value of the GPIO.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+/// Gets the GPIO value (for input GPIO only).
+/// @param gpio Pointer to the BGpio struct.
+/// @param value Output pointer to the value of the GPIO.
+/// @return Error code
 int BGpio_getValue(const BGpio* gpio, int* value);
 
-// Returns a file descriptor that can be used to poll on new data.
-//
-// Can be passed to select/epoll to wait for data to become available.
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
-//    fd: Output pointer to the file descriptor number.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+/// Returns a file descriptor that can be used to poll on new data.
+/// Can be passed to select/epoll to wait for data to become available.
+/// @param gpio Pointer to the BGpio struct.
+/// @param fd Output pointer to the file descriptor number.
+/// @return Error code (one of peripheral_error_t).
 int BGpio_getPollingFd(const BGpio* gpio, int* fd);
 
-// Destroys a BGpio struct.
-//
-// Arguments:
-//    gpio: Pointer to the BGpio struct.
+/// Destroys a BGpio struct.
+/// @param gpio Pointer to the BGpio struct.
 void BGpio_delete(BGpio* gpio);
 
+/// @}
+
 __END_DECLS
 
 #endif  // SYSTEM_PERIPHERALMANAGER_GPIO_H_
diff --git a/include/peripheralmanager/peripheral_manager_client.h b/include/peripheralmanager/peripheral_manager_client.h
index b394fb8..536bfde 100644
--- a/include/peripheralmanager/peripheral_manager_client.h
+++ b/include/peripheralmanager/peripheral_manager_client.h
@@ -25,63 +25,56 @@
 
 __BEGIN_DECLS
 
+/// @defgroup PeripheralManagerClient Peripheral client functions
+/// @brief Functions to access embedded peripherals
+/// @{
+
 typedef struct BPeripheralManagerClient BPeripheralManagerClient;
 
-// Returns the list of GPIOs.
-//
-// This does not take ownership into account.
-// The list must be freed by the caller.
-//
-// Arguments:
-//    client: Pointer to the BPeripheralManagerClient struct.
-//    num_gpio: Output pointer to the number of element in the list.
-//
-// Returns:
-//    The list of gpios.
+/// Returns the list of GPIOs.
+/// This does not take ownership into account.
+/// The list must be freed by the caller.
+/// @param client Pointer to the BPeripheralManagerClient struct.
+/// @param num_gpio Output pointer to the number of element in the list.
+/// @return The list of gpios.
 char** BPeripheralManagerClient_listGpio(const BPeripheralManagerClient* client,
                                          int* num_gpio);
 
-// Returns the list of available GPIOs.
-//
-// The list must be freed by the caller.
-//
-// Arguments:
-//    client: Pointer to the BPeripheralManagerClient struct.
-//    num_buses: Output pointer to the number of element in the list.
-//
-// Returns:
-//    The list of buses.
+/// Returns the list of available GPIOs.
+/// The list must be freed by the caller.
+/// @param client Pointer to the BPeripheralManagerClient struct.
+/// @param num_gpio Output pointer to the number of element in the list.
+/// @return The list of buses.
 char** BPeripheralManagerClient_listAvailableGpio(
     const BPeripheralManagerClient* client, int* num_gpio);
 
-// Opens a GPIO and takes ownership of it.
-//
-// Arguments:
-//    client: Pointer to the BPeripheralManagerClient struct.
-//    name: Name of the GPIO.
-//    gpio: Output pointer to the BGpio struct. Empty on error.
-//
-// Returns:
-//    Error code (one of peripheral_error_t).
+/// Opens a GPIO and takes ownership of it.
+/// @param client Pointer to the BPeripheralManagerClient struct.
+/// @param name Name of the GPIO.
+/// @param gpio Output pointer to the BGpio struct. Empty on error.
+/// @return Error code (one of peripheral_error_t).
 int BPeripheralManagerClient_openGpio(const BPeripheralManagerClient* client,
                                       const char* name,
                                       BGpio** gpio);
 
+/// Opens a SPI device and takes ownership of it.
+/// @oaram client Pointer to the BPeripheralManagerClient struct.
+/// @param name Name of the SPI device.
+/// @param dev Output pointer to the BSpiDevice struct. Empty on error.
+/// @return Error code (one of peripheral_error_t).
 int BPeripheralManagerClient_openSpiDevice(
     const BPeripheralManagerClient* client, const char* name, BSpiDevice** dev);
 
-// Creates a new client.
-//
-// Returns:
-//    A pointer to the created client. nullptr on errors.
+/// Creates a new client.
+/// @return A pointer to the created client. nullptr on errors.
 BPeripheralManagerClient* BPeripheralManagerClient_new();
 
-// Destroys the peripheral manager client.
-//
-// Arguments:
-//    client: Pointer to the BPeripheralManagerClient struct.
+/// Destroys the peripheral manager client.
+/// @param client Pointer to the BPeripheralManagerClient struct.
 void BPeripheralManagerClient_delete(BPeripheralManagerClient* client);
 
+/// @}
+
 __END_DECLS
 
 #endif  //  SYSTEM_PERIPHERALMANAGER_PERIPHERAL_MANAGER_CLIENT_H_