From e2baf5a833b8dcbf7722f866fc20731fe9a8433a Mon Sep 17 00:00:00 2001
From: Alessio Caiazza <nolith@abisso.org>
Date: Sat, 4 Dec 2021 19:17:00 +0100
Subject: [PATCH] Document functions with Doxygen format

---
 openrtx/include/chan.h                       | 50 +++++++++++++++++++-
 platform/targets/linux/emulator/sdl_engine.h | 16 +++++--
 2 files changed, 62 insertions(+), 4 deletions(-)

diff --git a/openrtx/include/chan.h b/openrtx/include/chan.h
index 54d78968..22e02fe7 100644
--- a/openrtx/include/chan.h
+++ b/openrtx/include/chan.h
@@ -20,7 +20,7 @@
 #include <pthread.h>
 #include <stdbool.h>
 
-/*
+/**
  * chan_t is an unbuffered synchronization channel.
  * Both reader and writer are blocked untill the data is exchanged.
  */
@@ -39,12 +39,60 @@ typedef struct chan_t
 }
 chan_t;
 
+/**
+ * This function initializes a channel.
+ *
+ * @param c: the cannel to initialize.
+ */
 void chan_init(chan_t *c);
+
+/**
+ * This function writes data into a channel.
+ * This is a synchronous write and the function blocks until a read happens.
+ *
+ * @param c: the channel.
+ * @param data: the data to publish on the channel.
+ */
 void chan_send(chan_t *c, void *data);
+
+/**
+ * This function reads data from a channel.
+ * This is a synchronous read and the function blocks until a write happens.
+ *
+ * @param c: the channel.
+ * @param data: the read data will be assigned to this pointer.
+ */
 void chan_recv(chan_t *c, void **data);
+
+/**
+ * This function check if the channel has a writer waiting with data.
+ *
+ * @param c: the channel.
+ * @return true if a writer is waiting on the channel.
+ */
 bool chan_can_recv(chan_t *c);
+
+/**
+ * This function check if the channel has a reader waiting for data.
+ *
+ * @param c: the channel.
+ * @return true if a reader is waiting on the channel.
+ */
 bool chan_can_send(chan_t *c);
+
+/**
+ * This function closes a channel.
+ * When a channel is closed, it is no longer possible to read or write from it.
+ *
+ * @param c: the channel.
+ */
 void chan_close(chan_t *c);
+
+/**
+ * Destructor function to de-allocate a channel.
+ *
+ * @param c: the channel.
+ */
 void chan_terminate(chan_t *c);
 
 #endif
diff --git a/platform/targets/linux/emulator/sdl_engine.h b/platform/targets/linux/emulator/sdl_engine.h
index 2703265c..d0e9f8b7 100644
--- a/platform/targets/linux/emulator/sdl_engine.h
+++ b/platform/targets/linux/emulator/sdl_engine.h
@@ -41,11 +41,21 @@
 #define PIXEL_SIZE uint32_t
 #endif
 
-/* Initialize the SDL engine. Must be called in the Main Thread */
+/**
+ * Initialize the SDL engine. Must be called in the Main Thread.
+ */
 void init_sdl();
-/* SDL main loop. Must be called in the Main Thread */
+
+/**
+ * SDL main loop. Must be called in the Main Thread.
+ */
 void sdl_task();
-/* Thread-safe check to verify if the application entered the SDL main loop. */
+
+/**
+ * Thread-safe check to verify if the application entered the SDL main loop.
+ *
+ * @return true after sdl_task() started.
+ */
 bool sdl_main_loop_ready();
 
 #endif /* SDL_ENGINE_H */