Doc comments and explanations

comm/messages.h

@@ -1,6 +1,12 @@
 //
 // Created by MightyPork on 2017/11/21.
 //
+// This is the only file to include from the comm/ folder directly.
+// Provides TinyFrame message types, utilities for forming payloads,
+// bulk read and write routines.
+//
+// See the other headers in the folder for prototypes.
+//
 
 #ifndef GEX_MESSAGES_H
 #define GEX_MESSAGES_H
@@ -36,9 +42,10 @@ enum Message_Types_ {
     MSG_PERSIST_CFG = 0x23,      //!< Write current settings to Flash (the equivalent of replacing the lock jumper)
 };
 
+/** The shared USB-serial TinyFrame instance */
 extern TinyFrame *comm;
 
-// Must be after the enum because it's used in the header file.
+// those must be after the enum because it's used in the header files
 #include "msg_responses.h"
 #include "msg_bulkread.h"
 #include "msg_bulkwrite.h"

comm/msg_bulkread.c

@@ -68,7 +68,7 @@ close:
     return TF_CLOSE;
 }
 
-/** Start the bulk read flow */
+
 void bulkread_start(TinyFrame *tf, BulkRead *bulk)
 {
     assert_param(bulk);

comm/msg_bulkread.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/12/23.
 //
+// Bulk read (providing data for bulk read by the PC)
+//
 
 #ifndef GEX_F072_MSG_BULKREAD_H
 #define GEX_F072_MSG_BULKREAD_H

comm/msg_bulkwrite.c

@@ -62,7 +62,7 @@ close:
     return TF_CLOSE;
 }
 
-/** Start the bulk write flow */
+
 void bulkwrite_start(TinyFrame *tf, BulkWrite *bulk)
 {
     assert_param(bulk);

comm/msg_bulkwrite.h

@@ -1,10 +1,16 @@
 //
 // Created by MightyPork on 2017/12/23.
 //
+// Bulk write (receiving bulk write from the PC)
+//
 
 #ifndef GEX_F072_MSG_BULKWRITE_H
 #define GEX_F072_MSG_BULKWRITE_H
 
+#ifndef GEX_MESSAGES_H
+#error "Include messages.h instead!"
+#endif
+
 #include <TinyFrame.h>
 
 typedef struct bulk_write BulkWrite;

comm/msg_responses.c

@@ -38,6 +38,7 @@ void com_respond_ok(TF_ID frame_id)
     com_respond_buf(frame_id, MSG_SUCCESS, NULL, 0);
 }
 
+
 void com_send_pb(TF_TYPE type, PayloadBuilder *pb)
 {
     uint32_t len;
@@ -45,6 +46,7 @@ void com_send_pb(TF_TYPE type, PayloadBuilder *pb)
     com_send_buf(type, buf, len);
 }
 
+
 void com_send_buf(TF_TYPE type, const uint8_t *buf, uint32_t len)
 {
     TF_Msg msg;

comm/msg_responses.h

@@ -1,6 +1,8 @@
 //
 // Created by MightyPork on 2017/12/22.
 //
+// Routines for sending TinyFrame responses.
+//
 
 #ifndef GEX_F072_MSG_RESPONSES_H
 #define GEX_F072_MSG_RESPONSES_H