Merge pull request #1778 from 0xc0170/dev_hal_doxy

hal - adding doxygen documentation

Author: 0xc0170

hal/hal/analogin_api.h

@@ -24,12 +24,39 @@
 extern "C" {
 #endif
 
+/** Analogin hal structure. analogin_s is declared in the target's hal
+ */
 typedef struct analogin_s analogin_t;
 
-void     analogin_init    (analogin_t *obj, PinName pin);
-float    analogin_read    (analogin_t *obj);
+/**
+ * \defgroup hal_analogin Analogin hal functions
+ * @{
+ */
+
+/** Initialize the analogin peripheral
+ *
+ * Configures the pin used by analogin.
+ * @param obj The analogin object to initialize
+ * @param pin The analogin pin name
+ */
+void analogin_init(analogin_t *obj, PinName pin);
+
+/** Read the input voltage, represented as a float in the range [0.0, 1.0]
+ *
+ * @param obj The analogin object
+ * @return A floating value representing the current input voltage
+ */
+float analogin_read(analogin_t *obj);
+
+/** Read the value from analogin pin, represented as an unsigned 16bit value
+ *
+ * @param obj The analogin object
+ * @return An unsigned 16bit value representing the current input voltage
+ */
 uint16_t analogin_read_u16(analogin_t *obj);
 
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif

hal/hal/analogout_api.h

@@ -24,14 +24,60 @@
 extern "C" {
 #endif
 
+/** Analogout hal structure. dac_s is declared in the target's hal
+ */
 typedef struct dac_s dac_t;
 
-void     analogout_init     (dac_t *obj, PinName pin);
-void     analogout_free     (dac_t *obj);
-void     analogout_write    (dac_t *obj, float value);
-void     analogout_write_u16(dac_t *obj, uint16_t value);
-float    analogout_read     (dac_t *obj);
-uint16_t analogout_read_u16 (dac_t *obj);
+/**
+ * \defgroup hal_analogout Analogout hal functions
+ * @{
+ */
+
+/** Initialize the analogout peripheral
+ *
+ * Configures the pin used by analogout.
+ * @param obj The analogout object to initialize
+ * @param pin The analogout pin name
+ */
+void analogout_init(dac_t *obj, PinName pin);
+
+/** Release the analogout object
+ *
+ * Note: This is not currently used in the mbed-drivers
+ * @param obj The analogout object
+ */
+void analogout_free(dac_t *obj);
+
+/** Set the output voltage, specified as a percentage (float)
+ *
+ * @param obj The analogin object
+ * @param value The floating-point output voltage to be set
+ */
+void analogout_write(dac_t *obj, float value);
+
+/** Set the output voltage, specified as unsigned 16-bit
+ *
+ * @param obj The analogin object
+ * @param value The unsigned 16-bit output voltage to be set
+ */
+void analogout_write_u16(dac_t *obj, uint16_t value);
+
+/** Read the current voltage value on the pin
+ *
+ * @param obj The analogin object
+ * @return A floating-point value representing the current voltage on the pin,
+ *     measured as a percentage
+ */
+float analogout_read(dac_t *obj);
+
+/** Read the current voltage value on the pin, as a normalized unsigned 16bit value
+ *
+ * @param obj The analogin object
+ * @return An unsigned 16-bit value representing the current voltage on the pin
+ */
+uint16_t analogout_read_u16(dac_t *obj);
+
+/**@}*/
 
 #ifdef __cplusplus
 }

hal/hal/gpio_api.h

@@ -16,40 +16,111 @@
 #ifndef MBED_GPIO_API_H
 #define MBED_GPIO_API_H
 
+#include <stdint.h>
 #include "device.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-/* Set the given pin as GPIO
+/**
+ * \defgroup hal_gpio GPIO HAL functions
+ * @{
+ */
+
+/** Set the given pin as GPIO
+ *
  * @param pin The pin to be set as GPIO
  * @return The GPIO port mask for this pin
  **/
 uint32_t gpio_set(PinName pin);
-
 /* Checks if gpio object is connected (pin was not initialized with NC)
  * @param pin The pin to be set as GPIO
  * @return 0 if port is initialized with NC
  **/
 int gpio_is_connected(const gpio_t *obj);
 
-/* GPIO object */
+/** Initialize the GPIO pin
+ *
+ * @param obj The GPIO object to initialize
+ * @param pin The GPIO pin to initialize
+ */
 void gpio_init(gpio_t *obj, PinName pin);
 
-void gpio_mode (gpio_t *obj, PinMode mode);
-void gpio_dir  (gpio_t *obj, PinDirection direction);
+/** Set the input pin mode
+ *
+ * @param obj  The GPIO object
+ * @param mode The pin mode to be set
+ */
+void gpio_mode(gpio_t *obj, PinMode mode);
+
+/** Set the pin direction
+ *
+ * @param obj       The GPIO object
+ * @param direction The pin direction to be set
+ */
+void gpio_dir(gpio_t *obj, PinDirection direction);
 
+/** Set the output value
+ *
+ * @param obj   The GPIO object
+ * @param value The value to be set
+ */
 void gpio_write(gpio_t *obj, int value);
-int  gpio_read (gpio_t *obj);
 
-// the following set of functions are generic and are implemented in the common gpio.c file
+/** Read the input value
+ *
+ * @param obj The GPIO object
+ * @return An integer value 1 or 0
+ */
+int gpio_read(gpio_t *obj);
+
+// the following functions are generic and implemented in the common gpio.c file
+// TODO: fix, will be moved to the common gpio header file
+
+/** Init the input pin and set mode to PullDefault
+ *
+ * @param obj The GPIO object
+ * @param pin The pin name
+ */
 void gpio_init_in(gpio_t* gpio, PinName pin);
+
+/** Init the input pin and set the mode
+ *
+ * @param obj  The GPIO object
+ * @param pin  The pin name
+ * @param mode The pin mode to be set
+ */
 void gpio_init_in_ex(gpio_t* gpio, PinName pin, PinMode mode);
+
+/** Init the output pin as an output, with predefined output value 0
+ *
+ * @param obj The GPIO object
+ * @param pin The pin name
+ * @return An integer value 1 or 0
+ */
 void gpio_init_out(gpio_t* gpio, PinName pin);
+
+/** Init the pin as an output and set the output value
+ *
+ * @param obj   The GPIO object
+ * @param pin   The pin name
+ * @param value The value to be set
+ */
 void gpio_init_out_ex(gpio_t* gpio, PinName pin, int value);
+
+/** Init the pin to be in/out
+ *
+ * @param obj       The GPIO object
+ * @param pin       The pin name
+ * @param direction The pin direction to be set
+ * @param mode      The pin mode to be set
+ * @param value     The value to be set for an output pin
+ */
 void gpio_init_inout(gpio_t* gpio, PinName pin, PinDirection direction, PinMode mode, int value);
 
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif

hal/hal/gpio_irq_api.h

@@ -24,22 +24,65 @@
 extern "C" {
 #endif
 
+/** GPIO IRQ events
+ */
 typedef enum {
     IRQ_NONE,
     IRQ_RISE,
     IRQ_FALL
 } gpio_irq_event;
 
+/** GPIO IRQ HAL structure. gpio_irq_s is declared in the target's HAL
+ */
 typedef struct gpio_irq_s gpio_irq_t;
 
 typedef void (*gpio_irq_handler)(uint32_t id, gpio_irq_event event);
 
-int  gpio_irq_init(gpio_irq_t *obj, PinName pin, gpio_irq_handler handler, uint32_t id);
+/**
+ * \defgroup hal_gpioirq GPIO IRQ HAL functions
+ * @{
+ */
+
+/** Initialize the GPIO IRQ pin
+ *
+ * @param obj     The GPIO object to initialize
+ * @param pin     The GPIO pin name
+ * @param handler The handler to be attached to GPIO IRQ
+ * @param id      The object ID (id != 0, 0 is reserved)
+ * @return -1 if pin is NC, 0 otherwise
+ */
+int gpio_irq_init(gpio_irq_t *obj, PinName pin, gpio_irq_handler handler, uint32_t id);
+
+/** Release the GPIO IRQ PIN
+ *
+ * @param obj The gpio object
+ */
 void gpio_irq_free(gpio_irq_t *obj);
-void gpio_irq_set (gpio_irq_t *obj, gpio_irq_event event, uint32_t enable);
+
+/** Enable/disable pin IRQ event
+ *
+ * @param obj    The GPIO object
+ * @param event  The GPIO IRQ event
+ * @param enable The enable flag
+ */
+void gpio_irq_set(gpio_irq_t *obj, gpio_irq_event event, uint32_t enable);
+
+/** Enable GPIO IRQ
+ *
+ * This is target dependent, as it might enable the entire port or just a pin
+ * @param obj The GPIO object
+ */
 void gpio_irq_enable(gpio_irq_t *obj);
+
+/** Disable GPIO IRQ
+ *
+ * This is target dependent, as it might disable the entire port or just a pin
+ * @param obj The GPIO object
+ */
 void gpio_irq_disable(gpio_irq_t *obj);
 
+/**@}*/
+
 #ifdef __cplusplus
 }
 #endif