add documentation in header files

1 files changed, 40 insertions, 25 deletions

diff --git a/stm32f091/server.h b/stm32f091/server.h
index 07c49d9..ba92b78 100644
--- a/stm32f091/server.h
+++ b/stm32f091/server.h
@@ -4,6 +4,7 @@
 #include <stdint.h>
 #include <stdbool.h>
 
+/** @brief store kind of AT command response the server is expecting */
 typedef enum {
 	WS_SERVER_LM_CMD_ECHO, /** @brief listen for echo of sent command */
 	WS_SERVER_LM_STATUS_CODE, /** @brief listen for busy, ERROR or OK */
@@ -12,39 +13,43 @@ typedef enum {
 	WS_SERVER_LM_CIPSEND_LISTENING, /** @brief AT+CIPSEND sent, now reading data */
 } ws_e_server_listen_mode;
 
+/** @brief state machine for parsing +IPD command fields */
 typedef enum {
 	WS_SERVER_CL_CHANNEL_ID, /** @brief listen channel id */
 	WS_SERVER_CL_DATA_LENGTH, /** @brief listen for data byte length */
 	WS_SERVER_CL_DATA_READ, /** @brief listen for data and pipe to ws_protocol_parse_req_byte */
 } ws_e_channel_listen_mode;
 
+/** @brief AT command status codes */
 typedef enum {
-	WS_SERVER_RC_NONE = -1,
-	WS_SERVER_RC_BUSY,
-	WS_SERVER_RC_ERR,
-	WS_SERVER_RC_OK,
+	WS_SERVER_RC_NONE = -1, /** @brief initial value */
+	WS_SERVER_RC_BUSY, /** @brief status code busy p... */
+	WS_SERVER_RC_ERR, /** @brief status code ERROR */
+	WS_SERVER_RC_OK, /** @brief status code OK */
 } ws_e_server_response_code;
 
+/** @brief counters for byte-by-byte string comparison of AT response codes */
 typedef struct {
-	uint8_t s_ok; /** @brief status code OK */
-	uint8_t s_error; /** @brief status code OK */
-	uint8_t s_fail; /** @brief status code OK */
-	uint8_t s_busy; /** @brief status code OK */
-	uint8_t i_ipd; /** @brief idle +IPD, */
-	uint8_t i_prompt; /** @brief idle > */
-	uint8_t l_send_ok; /** @brief ipd listen SEND OK */
-	uint8_t l_error; /** @brief ipd listen ERROR */
+	uint8_t s_ok; /** @brief counter for status code OK */
+	uint8_t s_error; /** @brief counter for status code OK */
+	uint8_t s_fail; /** @brief counter for status code OK */
+	uint8_t s_busy; /** @brief counter for status code OK */
+	uint8_t i_ipd; /** @brief counter for idle +IPD, */
+	uint8_t i_prompt; /** @brief counter for idle > */
+	uint8_t l_send_ok; /** @brief counter for ipd listen SEND OK */
+	uint8_t l_error; /** @brief counter for ipd listen ERROR */
 } ws_s_server_parser_response_counter;
 
+/** @brief server parser statue struct */
 typedef struct {
-	ws_e_server_listen_mode mode;
-	ws_e_server_response_code last_response;
-	unsigned int current_channel;
-	unsigned int channel_data_length;
-	unsigned int channel_data_counter;
-	ws_e_channel_listen_mode channel_listen_mode;
-	bool channel_data_ignore;
-	ws_s_server_parser_response_counter rc;
+	ws_e_server_listen_mode mode; /** @brief expected AT response kind */
+	ws_e_server_response_code last_response; /** @brief response code for last AT command */
+	unsigned int current_channel; /** @brief TCP channel for last +IPD command */
+	unsigned int channel_data_length; /** @brief data length for last +IPD command */
+	unsigned int channel_data_counter; /** @brief amount of parsed data bytes for last +IPD command */
+	ws_e_channel_listen_mode channel_listen_mode; /** @brief +IPD command parse state */
+	bool channel_data_ignore; /** @brief whether last TCP request should be ignored because it's too long */
+	ws_s_server_parser_response_counter rc; /** @brief response counters for byte-by-byte string comparison */
 } ws_s_server_parser;
 
 /** @brief global server parser struct */
@@ -62,11 +67,6 @@ extern ws_s_server_parser g_ws_server_parser;
  */
 void ws_server_req_incoming(uint8_t* data, size_t size);
 
-// /** @brief send AT response header for incoming request on specific channel */
-// void ws_server_req_respond_start(unsigned int channel);
-// /** @brief send AT tcp close on specific channel */
-// void ws_server_req_respond_end(unsigned int channel);
-
 /** @brief send data to esp, waiting until server returns to idle mode */
 void ws_server_send(uint8_t* data, size_t size);
 
@@ -93,7 +93,22 @@ void ws_server_req_parse_byte(unsigned int channel, uint8_t byte, bool ignore);
  */
 void ws_server_req_finish(unsigned int channel, bool ignore);
 
+/**
+ * @brief append data to the tx buffer for sending response in chunks
+ *
+ * the esp8266 becomes unreliable when sending large tcp responses, so this
+ * function buffers the complete response, and sends it in chunks broken up by
+ * a newline ('\n') character
+ *
+ * to send data buffered using this function, refer to
+ * `ws_server_buffer_request_chunk_send` and `ws_server_buffer_send_chunk`.
+ *
+ * @param data  pointer to data array
+ * @param size  size of data array
+ */
 void ws_server_buffer_send_append(uint8_t* data, size_t size);
 
+/** @brief send AT+CIPSEND with size of next chunk to the esp8266 */
 void ws_server_buffer_request_chunk_send();
+/** @brief send data chunk for last AT+CIPSEND command */
 void ws_server_buffer_send_chunk();