[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>

core/api-hal/api-gpio.h

@@ -12,39 +12,74 @@ typedef struct {
     GpioPin* gpio;
 } GpioDisableRecord;
 
-// init GPIO API
+/**
+ * Init GPIO API
+ * @return true on successful gpio initialization, false otherwize
+ */
 bool gpio_api_init();
 
-// init GPIO
+/**
+ * Init GPIO
+ * @param gpio GpioPin instance
+ * @param mode GpioMode gpio mode
+ */
 void gpio_init(const GpioPin* gpio, const GpioMode mode);
 
-// init GPIO, extended version
+/**
+ * Init GPIO, extended version
+ * @param gpio GpioPin instance
+ * @param mode GpioMode gpio mode
+ * @param pull GpioPull gpio pull mode
+ * @param speed GpioSpeed gpio speed
+ */
 void gpio_init_ex(
     const GpioPin* gpio,
     const GpioMode mode,
     const GpioPull pull,
     const GpioSpeed speed);
 
-// write value to GPIO, false = LOW, true = HIGH
+/**
+ * Write value to GPIO
+ * @param gpio GpioPin instance
+ * @param state false = LOW, true = HIGH
+ */
 static inline void gpio_write(const GpioPin* gpio, const bool state) {
     hal_gpio_write(gpio, state);
 }
 
-// read value from GPIO, false = LOW, true = HIGH
+/**
+ * Read value from GPIO
+ * @param gpio GpioPin instance
+ * @return false = LOW, true = HIGH
+ */
 static inline bool gpio_read(const GpioPin* gpio) {
     return hal_gpio_read(gpio);
 }
 
-// put GPIO to Z-state
+/**
+ * Put GPIO to Z-state
+ * @param gpio_record GpioDisableRecord instance
+ */
 void gpio_disable(GpioDisableRecord* gpio_record);
 
-// get GPIO record
+/**
+ * Get GPIO record
+ * @param name name of record
+ * @return ValueMutex instance
+ */
 ValueMutex* gpio_open_mutex(const char* name);
 
-// get GPIO record and acquire mutex
+/**
+ * Get GPIO record and acquire mutex
+ * @param name name of record
+ * @return GpioPin instance
+ */
 GpioPin* gpio_open(const char* name);
 
-// get RFID IN level
+/**
+ * Get RFID IN level
+ * @return false = LOW, true = HIGH
+ */
 bool get_rfid_in_level();
 
 #ifdef __cplusplus

core/api-hal/api-interrupt-mgr.h

@@ -6,8 +6,10 @@
 extern "C" {
 #endif
 
+/** Interrupt callback prototype */
 typedef void (*InterruptCallback)(void*, void*);
 
+/** Interupt type */
 typedef enum {
     InterruptTypeComparatorTrigger,
     InterruptTypeTimerCapture,
@@ -16,6 +18,7 @@ typedef enum {
     InterruptTypeExternalInterrupt,
 } InterruptType;
 
+/** Interrupt callback type */
 typedef struct {
     InterruptCallback callback;
     InterruptType type;
@@ -23,11 +26,46 @@ typedef struct {
     bool ready;
 } InterruptCallbackItem;
 
+/**
+ * Init interrupt
+ * @return true on succsessful initialization, false otherwise
+ */
 bool api_interrupt_init();
+
+/**
+ * Add interrupt
+ * @param callback InterruptCallback
+ * @param type InterruptType
+ * @param context context for callback
+ */
 void api_interrupt_add(InterruptCallback callback, InterruptType type, void* context);
+
+/**
+ * Remove interrupt
+ * @param callback InterruptCallback
+ * @param type InterruptType
+ */
 void api_interrupt_remove(InterruptCallback callback, InterruptType type);
+
+/**
+ * Enable interrupt
+ * @param callback InterruptCallback
+ * @param type InterruptType
+ */
 void api_interrupt_enable(InterruptCallback callback, InterruptType type);
+
+/**
+ * Disable interrupt
+ * @param callback InterruptCallback
+ * @param type InterruptType
+ */
 void api_interrupt_disable(InterruptCallback callback, InterruptType type);
+
+/**
+ * Call interrupt
+ * @param type InterruptType
+ * @param hw pointer to hardware peripheral
+ */
 void api_interrupt_call(InterruptType type, void* hw);
 
 #ifdef __cplusplus

core/furi/pubsub.h

@@ -7,13 +7,13 @@
 extern "C" {
 #endif
 
-/*
+/**
 == PubSub ==
 
-PubSub allows users to subscribe on notifies and notify subscribers.
+ * PubSub allows users to subscribe on notifies and notify subscribers.
-Notifier side can pass `void*` arg to subscriber callback,
+ * Notifier side can pass `void*` arg to subscriber callback,
-and also subscriber can set `void*` context pointer that pass into
+ * and also subscriber can set `void*` context pointer that pass into
-callback (you can see callback signature below).
+ * callback (you can see callback signature below).
  */
 
 typedef void (*PubSubCallback)(const void*, void*);
@@ -32,28 +32,28 @@ struct PubSubType {
     osMutexId_t mutex;
 };
 
-/*
+/**
-To create PubSub you should create PubSub instance and call `init_pubsub`.
+ * To create PubSub you should create PubSub instance and call `init_pubsub`.
  */
 bool init_pubsub(PubSub* pubsub);
 
-/*
+/**
-Since we use dynamic memory - we must explicity delete pubsub
+ * Since we use dynamic memory - we must explicity delete pubsub
  */
 bool delete_pubsub(PubSub* pubsub);
 
-/*
+/**
-Use `subscribe_pubsub` to register your callback.
+ * Use `subscribe_pubsub` to register your callback.
  */
 PubSubItem* subscribe_pubsub(PubSub* pubsub, PubSubCallback cb, void* ctx);
 
-/*
+/**
-Use `unsubscribe_pubsub` to unregister callback.
+ * Use `unsubscribe_pubsub` to unregister callback.
  */
 bool unsubscribe_pubsub(PubSubItem* pubsub_id);
 
-/*
+/**
-Use `notify_pubsub` to notify subscribers.
+ * Use `notify_pubsub` to notify subscribers.
  */
 bool notify_pubsub(PubSub* pubsub, void* arg);
 

core/furi/record.h

@@ -6,26 +6,30 @@
 extern "C" {
 #endif
 
-/* Initialize record storage
+/**
+ * Initialize record storage
  * For internal use only.
  */
 void furi_record_init();
 
-/* Create record
+/**
+ * Create record
  * @param name - record name
  * @param data - data pointer
  * @note Thread safe. Create and destroy must be executed from the same thread.
  */
 void furi_record_create(const char* name, void* data);
 
-/* Destroy record
+/**
+ * Destroy record
  * @param name - record name
  * @return true if successful, false if still have holders or thread is not owner.
  * @note Thread safe. Create and destroy must be executed from the same thread.
  */
 bool furi_record_destroy(const char* name);
 
-/* Open record
+/**
+ * Open record
  * @param name - record name
  * @return pointer to the record
  * @note Thread safe. Open and close must be executed from the same thread.
@@ -33,7 +37,8 @@ bool furi_record_destroy(const char* name);
  */
 void* furi_record_open(const char* name);
 
-/* Close record
+/**
+ * Close record
  * @param name - record name
  * @note Thread safe. Open and close must be executed from the same thread.
  */

core/furi/stdglue.h

@@ -7,7 +7,8 @@
 extern "C" {
 #endif
 
-/* Write callback
+/**
+ * Write callback
  * @param _cookie - pointer to cookie (see stdio gnu extension)
  * @param data - pointer to data
  * @param size - data size
@@ -15,17 +16,19 @@ extern "C" {
  */
 typedef void (*FuriStdglueWriteCallback)(void* _cookie, const char* data, size_t size);
 
-/* Initialized std library glue code */
+/** Initialized std library glue code */
 void furi_stdglue_init();
 
-/* Set global STDOUT callback
+/**
+ * Set global STDOUT callback
  * @param callback - callback or NULL to clear
  * @return true on success, otherwise fail
  * @warning function is thread aware, use this API from the same thread
  */
 bool furi_stdglue_set_global_stdout_callback(FuriStdglueWriteCallback callback);
 
-/* Set STDOUT callback for your thread 
+/**
+ * Set STDOUT callback for your thread
  * @param callback - callback or NULL to clear
  * @return true on success, otherwise fail
  * @warning function is thread aware, use this API from the same thread

core/furi/thread.h

@@ -8,88 +8,101 @@
 extern "C" {
 #endif
 
-/* FuriThreadState */
+/** FuriThreadState */
 typedef enum {
     FuriThreadStateStopped,
     FuriThreadStateStarting,
     FuriThreadStateRunning,
 } FuriThreadState;
 
-/* FuriThread anonymous structure */
+/** FuriThread anonymous structure */
 typedef struct FuriThread FuriThread;
 
-/* FuriThreadCallback
+/**
+ * FuriThreadCallback
  * Your callback to run in new thread
  * @warning don't use osThreadExit
  */
 typedef int32_t (*FuriThreadCallback)(void* context);
 
-/* FuriThread state change calback
+/**
+ * FuriThread state change calback
  * called upon thread state change
  * @param state - new thread state
  * @param context - callback context
  */
 typedef void (*FuriThreadStateCallback)(FuriThreadState state, void* context);
 
-/* Allocate FuriThread
+/**
+ * Allocate FuriThread
  * @return FuriThread instance
  */
 FuriThread* furi_thread_alloc();
 
-/* Release FuriThread
+/**
+ * Release FuriThread
  * @param thread - FuriThread instance
  */
 void furi_thread_free(FuriThread* thread);
 
-/* Set FuriThread name
+/**
+ * Set FuriThread name
  * @param thread - FuriThread instance
  * @param name - string
  */
 void furi_thread_set_name(FuriThread* thread, const char* name);
 
-/* Set FuriThread stack size
+/**
+ * Set FuriThread stack size
  * @param thread - FuriThread instance
  * @param stack_size - stack size in bytes
  */
 void furi_thread_set_stack_size(FuriThread* thread, size_t stack_size);
 
-/* Set FuriThread callback
+/**
+ * Set FuriThread callback
  * @param thread - FuriThread instance
  * @param callback - FuriThreadCallback, called upon thread run
  */
 void furi_thread_set_callback(FuriThread* thread, FuriThreadCallback callback);
 
-/* Set FuriThread context
+/**
+ * Set FuriThread context
  * @param thread - FuriThread instance
  * @param context - pointer to context for thread callback
  */
 void furi_thread_set_context(FuriThread* thread, void* context);
 
-/* Set FuriThread state change callback
+/**
+ * Set FuriThread state change callback
  * @param thread - FuriThread instance
  * @param callack - state change callback
  */
 void furi_thread_set_state_callback(FuriThread* thread, FuriThreadStateCallback callback);
 
-/* Set FuriThread state change context
+/**
+ * Set FuriThread state change context
  * @param thread - FuriThread instance
  * @param context - pointer to context
  */
 void furi_thread_set_state_context(FuriThread* thread, void* context);
 
-/* Get FuriThread state
+/**
+ * Get FuriThread state
  * @param thread - FuriThread instance
  * @return thread state from FuriThreadState
  */
 FuriThreadState furi_thread_get_state(FuriThread* thread);
 
-/* Start FuriThread
+/**
+ * Start FuriThread
  * @param thread - FuriThread instance
  * @return true on success
  */
 bool furi_thread_start(FuriThread* thread);
 
-/* Treminate FuriThread
+/**
+ * Treminate FuriThread
  * @param thread - FuriThread instance
  * @return osStatus_t
  * @warning terminating statefull thread is dangerous
@@ -97,7 +110,8 @@ bool furi_thread_start(FuriThread* thread);
  */
 osStatus_t furi_thread_terminate(FuriThread* thread);
 
-/* Join FuriThread
+/**
+ * Join FuriThread
  * @param thread - FuriThread instance
  * @return osStatus_t
  */

core/furi/valuemutex.h

@@ -7,12 +7,12 @@
 extern "C" {
 #endif
 
-/*
+/**
-== ValueMutex ==
+ * == ValueMutex ==
 
-The most simple concept is ValueMutex.
+ * The most simple concept is ValueMutex.
-It is wrapper around mutex and value pointer.
+ * It is wrapper around mutex and value pointer.
-You can take and give mutex to work with value and read and write value.
+ * You can take and give mutex to work with value and read and write value.
  */
 
 typedef struct {
@@ -21,31 +21,31 @@ typedef struct {
     osMutexId_t mutex;
 } ValueMutex;
 
-/*
+/**
-Creates ValueMutex.
+ * Creates ValueMutex.
  */
 bool init_mutex(ValueMutex* valuemutex, void* value, size_t size);
 
-/*
+/**
-Free resources allocated by `init_mutex`.
+ * Free resources allocated by `init_mutex`.
-This function doesn't free the memory occupied by `ValueMutex` itself.
+ * This function doesn't free the memory occupied by `ValueMutex` itself.
  */
 bool delete_mutex(ValueMutex* valuemutex);
 
-/*
+/**
-Call for work with data stored in mutex.
+ * Call for work with data stored in mutex.
-Returns pointer to data if success, NULL otherwise.
+ * @return pointer to data if success, NULL otherwise.
  */
 void* acquire_mutex(ValueMutex* valuemutex, uint32_t timeout);
 
-/*
+/**
-Helper: infinitly wait for mutex
+ * Helper: infinitly wait for mutex
  */
 static inline void* acquire_mutex_block(ValueMutex* valuemutex) {
     return acquire_mutex(valuemutex, osWaitForever);
 }
 
-/* 
+/**
  * With statement for value mutex, acts as lambda
  * @param name a resource name, const char*
  * @param function_body a (){} lambda declaration,
@@ -59,15 +59,15 @@ static inline void* acquire_mutex_block(ValueMutex* valuemutex) {
         release_mutex(value_mutex, p);               \
     }
 
-/*
+/**
-Release mutex after end of work with data.
+ * Release mutex after end of work with data.
-Call `release_mutex` and pass ValueData instance and pointer to data.
+ * Call `release_mutex` and pass ValueData instance and pointer to data.
  */
 bool release_mutex(ValueMutex* valuemutex, const void* value);
 
-/*
+/**
-Instead of take-access-give sequence you can use `read_mutex` and `write_mutex` functions.
+ * Instead of take-access-give sequence you can use `read_mutex` and `write_mutex` functions.
-Both functions return true in case of success, false otherwise.
+ * Both functions return true in case of success, false otherwise.
  */
 bool read_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout);
 

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);
 
-/**
+/** Enable 3.3v on external gpio and sd card */
- * @brief Enable 3.3v on external gpio and sd card
- */
 void api_hal_power_enable_external_3_3v();
 
-/**
+/** Disable 3.3v on external gpio and sd card */
- * @brief 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
 
-/**
+/** Init SD card detect */
- * @brief Init SD card detect
- * 
- */
 void hal_sd_detect_init(void);
 
-/**
+/** Set SD card detect pin to low */
- * @brief 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();

lib/drivers/bq25896.h

@@ -3,32 +3,32 @@
 #include <stdbool.h>
 #include <stdint.h>
 
-/* Initialize Driver */
+/** Initialize Driver */
 void bq25896_init();
 
-/* Send device into shipping mode */
+/** Send device into shipping mode */
 void bq25896_poweroff();
 
-/* Is currently charging */
+/** Is currently charging */
 bool bq25896_is_charging();
 
-/* Enable otg */
+/** Enable otg */
 void bq25896_enable_otg();
 
-/* Disable otg */
+/** Disable otg */
 void bq25896_disable_otg();
 
-/* Get VBUS Voltage in mV */
+/** Get VBUS Voltage in mV */
 uint16_t bq25896_get_vbus_voltage();
 
-/* Get VSYS Voltage in mV */
+/** Get VSYS Voltage in mV */
 uint16_t bq25896_get_vsys_voltage();
 
-/* Get VBAT Voltage in mV */
+/** Get VBAT Voltage in mV */
 uint16_t bq25896_get_vbat_voltage();
 
-/* Get VBAT current in mA */
+/** Get VBAT current in mA */
 uint16_t bq25896_get_vbat_current();
 
-/* Get NTC voltage in mpct of REGN */
+/** Get NTC voltage in mpct of REGN */
 uint32_t bq25896_get_ntc_mpct();

lib/drivers/bq27220.h

@@ -43,32 +43,32 @@ typedef struct {
     uint8_t RSVD0 : 5;
 } OperationStatus;
 
-/* Initialize Driver */
+/** Initialize Driver */
 void bq27220_init();
 
-/* Get battery voltage in mV or error */
+/** Get battery voltage in mV or error */
 uint16_t bq27220_get_voltage();
 
-/* Get current in mA or error*/
+/** Get current in mA or error*/
 int16_t bq27220_get_current();
 
-/* Get battery status */
+/** Get battery status */
 uint8_t bq27220_get_battery_status(BatteryStatus* battery_status);
 
-/* Get operation status */
+/** Get operation status */
 uint8_t bq27220_get_operation_status(OperationStatus* operation_status);
 
-/* Get temperature in units of 0.1°K */
+/** Get temperature in units of 0.1°K */
 uint16_t bq27220_get_temperature();
 
-/* Get compensated full charge capacity in in mAh */
+/** Get compensated full charge capacity in in mAh */
 uint16_t bq27220_get_full_charge_capacity();
 
-/* Get remaining capacity in in mAh */
+/** Get remaining capacity in in mAh */
 uint16_t bq27220_get_remaining_capacity();
 
-/* Get predicted remaining battery capacity in percents */
+/** Get predicted remaining battery capacity in percents */
 uint16_t bq27220_get_state_of_charge();
 
-/* Get ratio of full charge capacity over design capacity in percents */
+/** Get ratio of full charge capacity over design capacity in percents */
 uint16_t bq27220_get_state_of_health();

lib/drivers/lp5562.h

@@ -3,6 +3,7 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/** Channel types */
 typedef enum {
     LP5562ChannelRed,
     LP5562ChannelGreen,
@@ -10,13 +11,17 @@ typedef enum {
     LP5562ChannelWhite,
 } LP5562Channel;
 
-/* Initialize Driver */
+/** Initialize Driver */
 void lp5562_reset();
 
+/** Configure Driver */
 void lp5562_configure();
 
+/** Enable Driver */
 void lp5562_enable();
 
+/** Set channel current */
 void lp5562_set_channel_current(LP5562Channel channel, uint8_t value);
 
+/** Set channel current */
 void lp5562_set_channel_value(LP5562Channel channel, uint8_t value);