more doc comments

tasks/sched_queue.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/11/21.
 //
+// Job and message scheduling queue structs and typedefs
+//
 
 #ifndef GEX_SCHED_QUEUE_H
 #define GEX_SCHED_QUEUE_H
@@ -8,36 +10,55 @@
 #include "platform.h"
 #include <TinyFrame.h>
 
+/**
+ * Queued job typedef
+ */
 typedef struct sched_que_item Job;
+
+/**
+ * Queued job callback
+ */
 typedef void (*ScheduledJobCb) (Job *job);
 
+/**
+ * Queued job data struct
+ */
 struct sched_que_item {
+    /** The callback */
     ScheduledJobCb cb;
+    /** Data word 1 */
     union {
-        TF_ID frame_id;
-        void *data1;
+        TF_ID frame_id; // typically used to pass frame id to the callback
+        void *data1; // arbitrary pointer or int
     };
+    /** Data word 2 */
     union {
-        uint32_t d32;
-        uint8_t *buf;
-        const uint8_t *cbuf;
-        const char *str;
-        void *data2;
+        uint32_t d32; // passing a number
+        uint8_t *buf; // uchar buffer
+        const uint8_t *cbuf; // const uchar buffer
+        const char *str; // string
+        void *data2; // arbitrary pointer
     };
+    /** Data word 3 */
     union {
-        uint32_t len;
-        void *data3;
+        uint32_t len; // typically length of the buffer
+        void *data3; // arbitrary pointer
     };
 };
 
-// This que is used to stash frames received from TinyFrame for later evaluation on the application thread
+/**
+ * Queued data chunk structure - used for buffering received messages for TinyFrame
+ */
 struct rx_que_item {
     uint32_t len;
     uint8_t data[MSG_QUE_SLOT_SIZE];
 };
 
+/**
+ * Combined struct - added when we merged the two separate queues
+ */
 struct rx_sched_combined_que_item {
-    bool is_job;
+    bool is_job; // tag indicating whether the job or msg field is used
     union {
         struct rx_que_item msg;
         struct sched_que_item job;

tasks/task_main.h

@@ -1,13 +1,19 @@
 //
 // Created by MightyPork on 2017/11/09.
 //
+// Main GEX thread. Handles USB communication, heartbeat LED blinking and VFS reconnect timeouts.
+// The thread is notified via flag bits about events from the USB IRQs
+//
 
 #ifndef GEX_TASK_MAIN_H
 #define GEX_TASK_MAIN_H
 
 #include "platform.h"
 
+/** Main thread handle */
 extern osThreadId tskMainHandle;
+
+/** Main thread entry point */
 void TaskMain(const void *argument);
 
 // Notify flags:

tasks/task_msg.h

@@ -1,6 +1,9 @@
 //
 // Created by MightyPork on 2017/12/22.
 //
+// Message and job combined queue, used for async job execution (dispatched form ISR)
+// and TinyFrame message handling
+//
 
 #ifndef GEX_F072_TASK_MSG_H
 #define GEX_F072_TASK_MSG_H
@@ -8,15 +11,32 @@
 #include "platform.h"
 #include "sched_queue.h"
 
+/** Message queue handle */
 extern osMessageQId queMsgJobHandle;
+
+/** Message/job thread handle */
 extern osThreadId tskMsgJobHandle;
+
+/** Message/job thread entry point */
 void TaskMsgJob(const void *argument);
+
+/**
+ * Add a job to the queue
+ *
+ * @param job
+ */
 void scheduleJob(Job *job);
 
+/**
+ * Add a message to the queue. This always takes the entire slot (64 bytes) or multiple
+ *
+ * @param buf - byte buffer
+ * @param len - number of bytes; can exceed 64 - then it will be split to multiple slots
+ */
+void rxQuePostMsg(uint8_t *buf, uint32_t len);
+
 #if USE_STACK_MONITOR
 extern volatile uint32_t msgQueHighWaterMark;
 #endif
 
-void rxQuePostMsg(uint8_t *buf, uint32_t len);
-
 #endif //GEX_F072_TASK_MSG_H