Document functions with Doxygen format

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

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 */