[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,14 +7,14 @@
 extern "C" {
 #endif
 
-/*
+/**
 == PubSub ==
 
-PubSub allows users to subscribe on notifies and notify subscribers.
-Notifier side can pass `void*` arg to subscriber callback,
-and also subscriber can set `void*` context pointer that pass into
-callback (you can see callback signature below).
-*/
+ * PubSub allows users to subscribe on notifies and notify subscribers.
+ * Notifier side can pass `void*` arg to subscriber callback,
+ * and also subscriber can set `void*` context pointer that pass into
+ * callback (you can see callback signature below).
+ */
 
 typedef void (*PubSubCallback)(const void*, void*);
 typedef struct PubSubType PubSub;
@@ -32,29 +32,29 @@ 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);
 
 #ifdef __cplusplus

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,13 +7,13 @@
 extern "C" {
 #endif
 
-/*
-== ValueMutex ==
+/**
+ * == ValueMutex ==
 
-The most simple concept is ValueMutex.
-It is wrapper around mutex and value pointer.
-You can take and give mutex to work with value and read and write value.
-*/
+ * The most simple concept is ValueMutex.
+ * It is wrapper around mutex and value pointer.
+ * You can take and give mutex to work with value and read and write value.
+ */
 
 typedef struct {
     void* value;
@@ -21,36 +21,36 @@ 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`.
-This function doesn't free the memory occupied by `ValueMutex` itself.
-*/
+/**
+ * Free resources allocated by `init_mutex`.
+ * This function doesn't free the memory occupied by `ValueMutex` itself.
+ */
 bool delete_mutex(ValueMutex* valuemutex);
 
-/*
-Call for work with data stored in mutex.
-Returns pointer to data if success, NULL otherwise.
-*/
+/**
+ * Call for work with data stored in mutex.
+ * @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,
  * executed within you parent function context.
-*/
+ */
 #define with_value_mutex(value_mutex, function_body) \
     {                                                \
         void* p = acquire_mutex_block(value_mutex);  \
@@ -59,16 +59,16 @@ static inline void* acquire_mutex_block(ValueMutex* valuemutex) {
         release_mutex(value_mutex, p);               \
     }
 
-/*
-Release mutex after end of work with data.
-Call `release_mutex` and pass ValueData instance and pointer to data.
-*/
+/**
+ * Release mutex after end of work with 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.
-Both functions return true in case of success, false otherwise.
-*/
+/**
+ * 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.
+ */
 bool read_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout);
 
 bool write_mutex(ValueMutex* valuemutex, void* data, size_t len, uint32_t timeout);