[FL-41] api-hal doxygen documentation (#387)

* targets/api-hal: rework documentation in doxygen style
* core/api-hal: rework documentation in doxygen style
* core/furi: rework documentation in doxygen style
* drivers: rework documentation in doxygen style

Co-authored-by: あく <alleteam@gmail.com>

firmware/targets/api-hal-include/api-hal-boot.h

@@ -4,11 +4,13 @@
 extern "C" {
 #endif
 
+/** Boot modes */
 typedef enum {
     ApiHalBootModeNormal,
     ApiHalBootModeDFU
 } ApiHalBootMode;
 
+/** Set boot mode */
 void api_hal_boot_set_mode(ApiHalBootMode mode);
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-bt.h

@@ -7,42 +7,43 @@
 extern "C" {
 #endif
 
-/* Initialize */
+/** Initialize */
 void api_hal_bt_init();
 
-/* Start BLE app */
+/** Start BLE app */
 bool api_hal_bt_start_app();
 
-/* Get BT/BLE system component state */
+/** Get BT/BLE system component state */
 void api_hal_bt_dump_state(string_t buffer);
 
-/* Get BT/BLE system component state */
+/** Get BT/BLE system component state */
 bool api_hal_bt_is_alive();
 
-/* Lock shared access to flash controller
+/**
+ * Lock shared access to flash controller
  * @return true if lock was successful, false if not
  */
 bool api_hal_bt_lock_flash();
 
-/* Unlock shared access to flash controller */
+/** Unlock shared access to flash controller */
 void api_hal_bt_unlock_flash();
 
-/* Start ble tone tx at given channel and power */
+/** Start ble tone tx at given channel and power */
 void api_hal_bt_start_tone_tx(uint8_t tx_channel, uint8_t power);
 
-/* Stop ble tone tx */
+/** Stop ble tone tx */
 void api_hal_bt_stop_tone_tx();
 
-/* Start sending ble packets at a given frequency and datarate */
+/** Start sending ble packets at a given frequency and datarate */
 void api_hal_bt_start_packet_tx(uint8_t frequency, uint8_t datarate);
 
-/* Stop sending ble packets */
+/** Stop sending ble packets */
 void api_hal_bt_stop_packet_tx();
 
-/* Set up the RF to listen to a given RF channel */
+/** Set up the RF to listen to a given RF channel */
 void api_hal_bt_start_rx(uint8_t frequency);
 
-/* Stop RF listenning */
+/** Stop RF listenning */
 void api_hal_bt_stop_rx();
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-delay.h

@@ -5,8 +5,16 @@
 extern "C" {
 #endif
 
+/**
+ * Delay in milliseconds
+ * @warning Cannot be used from ISR
+ */
 void delay(float milliseconds);
+
+/** Delay in microseconds */
 void delay_us(float microseconds);
+
+/** Init DWT */
 void delay_us_init_DWT(void);
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-i2c.h

@@ -8,8 +8,18 @@
 extern "C" {
 #endif
 
+/** Init I2C */
 void api_hal_i2c_init();
 
+/**
+ * Perform I2C tx transfer
+ * @param instance I2C_TypeDef instance
+ * @param address I2C slave address
+ * @param data pointer to data buffer
+ * @param size size of data buffer
+ * @param timeout timeout in CPU ticks
+ * @return true on successful transfer, false otherwise
+ */
 bool api_hal_i2c_tx(
     I2C_TypeDef* instance,
     const uint8_t address,
@@ -17,6 +27,15 @@ bool api_hal_i2c_tx(
     const uint8_t size,
     uint32_t timeout);
 
+/**
+ * Perform I2C rx transfer
+ * @param instance I2C_TypeDef instance
+ * @param address I2C slave address
+ * @param data pointer to data buffer
+ * @param size size of data buffer
+ * @param timeout timeout in CPU ticks
+ * @return true on successful transfer, false otherwise
+ */
 bool api_hal_i2c_rx(
     I2C_TypeDef* instance,
     const uint8_t address,
@@ -24,6 +43,17 @@ bool api_hal_i2c_rx(
     const uint8_t size,
     uint32_t timeout);
 
+/**
+ * Perform I2C tx and rx transfers
+ * @param instance I2C_TypeDef instance
+ * @param address I2C slave address
+ * @param tx_data pointer to tx data buffer
+ * @param tx_size size of tx data buffer
+ * @param rx_data pointer to rx data buffer
+ * @param rx_size size of rx data buffer
+ * @param timeout timeout in CPU ticks
+ * @return true on successful transfer, false otherwise
+ */
 bool api_hal_i2c_trx(
     I2C_TypeDef* instance,
     const uint8_t address,
@@ -33,10 +63,18 @@ bool api_hal_i2c_trx(
     const uint8_t rx_size,
     uint32_t timeout);
 
+/** Acquire I2C mutex */
 void api_hal_i2c_lock();
 
+/** Release I2C mutex */
 void api_hal_i2c_unlock();
 
+/**
+ * With clause for I2C peripheral
+ * @param type type of function_body
+ * @param pointer pointer to return of function_body
+ * @param function_body a (){} lambda declaration, executed with I2C mutex acquired
+ */
 #define with_api_hal_i2c(type, pointer, function_body)        \
     {                                                         \
         api_hal_i2c_lock();                                   \

firmware/targets/api-hal-include/api-hal-light.h

@@ -8,8 +8,14 @@
 extern "C" {
 #endif
 
+/** Init light driver */
 void api_hal_light_init();
 
+/**
+ * Set light value
+ * @param light - Light
+ * @param value - light brightness [0-255]
+ */
 void api_hal_light_set(Light light, uint8_t value);
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-power.h

@@ -8,89 +8,89 @@
 extern "C" {
 #endif
 
+/** Power IC type */
 typedef enum {
     ApiHalPowerICCharger,
     ApiHalPowerICFuelGauge,
 } ApiHalPowerIC;
 
-/* Initialize drivers */
+/** Initialize drivers */
 void api_hal_power_init();
 
-/* Get current insomnia level
+/**
+ * Get current insomnia level
  * @return insomnia level: 0 - no insomnia, >0 - insomnia, bearer count.
  */
 uint16_t api_hal_power_insomnia_level();
 
-/* Enter insomnia mode
+/**
+ * Enter insomnia mode
  * Prevents device from going to sleep
  * @warning Internally increases insomnia level
  * Must be paired with api_hal_power_insomnia_exit
  */
 void api_hal_power_insomnia_enter();
 
-/* Exit insomnia mode
+/**
+ * Exit insomnia mode
  * Allow device to go to sleep
  * @warning Internally decreases insomnia level.
  * Must be paired with api_hal_power_insomnia_enter
  */
 void api_hal_power_insomnia_exit();
 
-/* Check if deep sleep availble */
+/** Check if deep sleep availble */
 bool api_hal_power_deep_available();
 
-/* Go to sleep */
+/** Go to sleep */
 void api_hal_power_sleep();
 
-/* Get predicted remaining battery capacity in percents */
+/** Get predicted remaining battery capacity in percents */
 uint8_t api_hal_power_get_pct();
 
-/* Get battery health state in percents */
+/** Get battery health state in percents */
 uint8_t api_hal_power_get_bat_health_pct();
 
-/* Get charging status */
+/** Get charging status */
 bool api_hal_power_is_charging();
 
-/* Poweroff system */
+/** Poweroff system */
 void api_hal_power_off();
 
-/* OTG enable */
+/** OTG enable */
 void api_hal_power_enable_otg();
 
-/* OTG disable */
+/** OTG disable */
 void api_hal_power_disable_otg();
 
-/* Get remaining battery battery capacity in mAh */
+/** Get remaining battery battery capacity in mAh */
 uint32_t api_hal_power_get_battery_remaining_capacity();
 
-/* Get full charge battery capacity in mAh */
+/** Get full charge battery capacity in mAh */
 uint32_t api_hal_power_get_battery_full_capacity();
 
-/* Get battery voltage in V */
+/** Get battery voltage in V */
 float api_hal_power_get_battery_voltage(ApiHalPowerIC ic);
 
-/* Get battery current in A */
+/** Get battery current in A */
 float api_hal_power_get_battery_current(ApiHalPowerIC ic);
 
-/* Get temperature in C */
+/** Get temperature in C */
 float api_hal_power_get_battery_temperature(ApiHalPowerIC ic);
 
-/* Get System voltage in V */
+/** Get System voltage in V */
 float api_hal_power_get_system_voltage();
 
-/* Get USB voltage in V */
+/** Get USB voltage in V */
 float api_hal_power_get_usb_voltage();
 
-/* Get power system component state */
+/** Get power system component state */
 void api_hal_power_dump_state(string_t buffer);
 
-/**
- * @brief Enable 3.3v on external gpio and sd card
- */
+/** Enable 3.3v on external gpio and sd card */
 void api_hal_power_enable_external_3_3v();
 
-/**
- * @brief Disable 3.3v on external gpio and sd card
- */
+/** Disable 3.3v on external gpio and sd card */
 void api_hal_power_disable_external_3_3v();
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-sd.h

@@ -5,21 +5,14 @@
 extern "C" {
 #endif
 
-/**
- * @brief Init SD card detect
- * 
- */
+/** Init SD card detect */
 void hal_sd_detect_init(void);
 
-/**
- * @brief Set SD card detect pin to low
- * 
- */
+/** Set SD card detect pin to low */
 void hal_sd_detect_set_low(void);
 
 /**
- * @brief Get SD card status
- * 
+ * Get SD card status
  * @return true if SD card present
  * @return false if SD card not present
  */

firmware/targets/api-hal-include/api-hal-subghz.h

@@ -4,6 +4,7 @@
 extern "C" {
 #endif
 
+/** Sub-GHz band type */
 typedef enum {
     RfBandIsolation = 0,
     RfBand1 = 1,
@@ -11,6 +12,10 @@ typedef enum {
     RfBand3 = 3
 } RfBand;
 
+/**
+ * Set Sub-GHz band
+ * @param band RfBand
+ */
 void api_hal_rf_band_set(RfBand band);
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-uid.h

@@ -7,10 +7,10 @@
 extern "C" {
 #endif
 
-/* Get platform UID size in bytes */
+/** Get platform UID size in bytes */
 size_t api_hal_uid_size();
 
-/* Get const pointer to UID */
+/** Get const pointer to UID */
 const uint8_t* api_hal_uid();
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-vcp.h

@@ -8,12 +8,14 @@
 extern "C" {
 #endif
 
-/* Init VCP HAL
+/**
+ * Init VCP HAL
  * Allocates ring buffer and initializes state
  */
 void api_hal_vcp_init();
 
-/* Recieve data from VCP
+/**
+ * Recieve data from VCP
  * Waits till some data arrives, never returns 0
  * @param buffer - pointer to buffer
  * @param size - buffer size
@@ -21,7 +23,8 @@ void api_hal_vcp_init();
  */
 size_t api_hal_vcp_rx(uint8_t* buffer, size_t size);
 
-/* Transmit data to VCP
+/**
+ * Transmit data to VCP
  * @param buffer - pointer to buffer
  * @param size - buffer size
  */

firmware/targets/api-hal-include/api-hal-version.h

@@ -8,18 +8,25 @@
 extern "C" {
 #endif
 
+/** Check target firmware version */
 bool api_hal_version_do_i_belong_here();
 
+/** Get hardware version */
 const uint8_t api_hal_version_get_hw_version();
 
+/** Get hardware target */
 const uint8_t api_hal_version_get_hw_target();
 
+/** Get hardware body */
 const uint8_t api_hal_version_get_hw_body();
 
+/** Get hardware connect */
 const uint8_t api_hal_version_get_hw_connect();
 
+/** Get hardware timestamp */
 const uint32_t api_hal_version_get_hw_timestamp();
 
+/** Get pointer to target name */
 const char * api_hal_version_get_name_ptr();
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal-vibro.h

@@ -8,10 +8,10 @@
 extern "C" {
 #endif
 
-/* Initialize vibro */
+/** Initialize vibro */
 void api_hal_vibro_init();
 
-/* Turn on/off vibro */
+/** Turn on/off vibro */
 void api_hal_vibro_on(bool value);
 
 #ifdef __cplusplus

firmware/targets/api-hal-include/api-hal.h

@@ -24,4 +24,5 @@ template <unsigned int N> struct STOP_EXTERNING_ME {};
 #include "api-hal-subghz.h"
 #include "api-hal-vibro.h"
 
+/** Init api-hal */
 void api_hal_init();