Added comments. (#14)

Co-authored-by: Sercan Uzun <sercan.uzun@campus.tu-berlin.de>

Author: srcnuzn

STM32CubeIDE/Application/includes/mqtt.h

@@ -3,6 +3,9 @@
  *
  *  Created on: 08.05.2021
  *      Author: serca
+ *
+ *      TODO: Add comments for mqtt.h
+ *
  */
 
 #ifndef INCLUDES_MQTT_H_

STM32CubeIDE/Application/includes/mqtt_required.h

@@ -4,7 +4,7 @@
  *  Created on: 21.05.2021
  *      Author: serca
  *
- *  TODO: File Header for mqtt_required.h
+ *  TODO: Add Comment for mqtt_required.h
  */
 
 #ifndef INCLUDES_MQTT_REQUIRED_H_
@@ -14,14 +14,14 @@
 /* Target specific functions to be implemented by user --------------------------------------*/
 
 /*
- * @brief	Provides a tick value in millisecond.
+ * @brief	Must provide a tick value in millisecond.
  * @note	This target-specific function must be implemented by user.
  * @retval	tick value (uint32) in milliseconds
  */
 extern uint32_t MqttClient_GetTick();
 
 /*
- * @brief	Performs a software-reset of the microcontroller.
+ * @brief	Must performs a software-reset of the microcontroller.
  * @note	This target-specific function must be implemented by user.
  * @retval	None
  */
@@ -31,7 +31,7 @@ extern void MqttClient_HandleSystemResetRequest();
 /* Application specific functions to be implemented by user ---------------------------------*/
 
 /*
- * @brief	Writes the JSON-message to be published.
+ * @brief	Must prepare the JSON-message to be published.
  * @note	This application-specific function must be implemented by user.
  * 			To write the JSON-message, following functions can be used:
  * 				- MqttClient_PublishInteger
@@ -44,7 +44,7 @@ extern void MqttClient_HandleSystemResetRequest();
 extern void MqttClient_Publish();
 
 /*
- * @brief	Registers user-specific callbacks to given events.
+ * @brief	Must register user-specific callbacks.
  * @note	This application-specific function must be implemented by user.
  * 			To register callbacks, following functions can be used:
  * 				- MqttClient_RegisterSubscribeCallback

STM32CubeIDE/Application/includes/wizfi360.h

@@ -1,8 +1,11 @@
 /*
- * test.h
+ * wizfi360.h
  *
  *  Created on: 29.04.2021
  *      Author: soenk
+ *
+ *  TODO: Add Comment for wizfi360.h
+ *
  */
 
 #ifndef INCLUDES_WIZFI360_H_
@@ -287,25 +290,27 @@ typedef struct __WIZFI360_HandlerTypedef
 
 	WIZFI360_CommandIdTypeDef CommandId;				/*!< Identifies the ongoing/last AT command */
 
-	uint8_t TagCharsReceived[WIZFI360_NUM_TAGS];		/*!< The amount of consecutive tag characters found in UART receive buffer. */
+	uint8_t TagCharsReceived[WIZFI360_NUM_TAGS];		/*!< The amount of consecutive tag characters found in UartRxBuffer. */
 
-	uint8_t EchoCharsReceived;							/*!< The amount of consecutive echo characters found in UART receive buffer. */
+	uint8_t EchoCharsReceived;							/*!< The amount of consecutive echo characters found in UartRxBuffer. */
 
 	uint8_t WifiState;									/*!< Indicates, weather the module is connected to an AP or not. */
 
-	ring_buffer_t UartRxBuffer;							/*!< TODO: Comment on UartRxBuffer */
+	ring_buffer_t UartRxBuffer;							/*!< Ring-buffer for received UART data. */
 
 
-	char SubTopics[WIZFI360_MAX_SUBTOPIC_CALLBACKS]		/*!< TODO: Comment on SubTopics */
+	char SubTopics[WIZFI360_MAX_SUBTOPIC_CALLBACKS]		/*!< List of subscribe-topic strings, that we listen to. */
 					  [WIZFI360_MAX_SUBTOPIC_SCAN_LEN];
 
-	void (*SubTopicCallbacks[WIZFI360_MAX_SUBTOPIC_CALLBACKS]) (char*);	/*!< TODO: Comment on SubTopicCallbacks */
+	void (*SubTopicCallbacks[
+		WIZFI360_MAX_SUBTOPIC_CALLBACKS]) (char*);		/*!< List of callback functions (mapped to SubTopics) */
 
-	uint8_t SubTopicCharsReceived[WIZFI360_MAX_SUBTOPIC_CALLBACKS];	/*!< TODO: Comment on SubTopicCharsReceived */
+	uint8_t SubTopicCharsReceived[
+		WIZFI360_MAX_SUBTOPIC_CALLBACKS];				/*!< Amount of consecutive topic characters found in UartRxBuffer. */
 
-	uint8_t NumSubTopicCallbacks;						/*!< TODO: Comment on NumSubTopicCallbacks */
+	uint8_t NumSubTopicCallbacks;						/*!< Number of subscribe-topics, that we listen to */
 
-	uint8_t MessageIncoming;
+	uint8_t MessageIncoming;							/*!< Indicates, that a subscribe topic was found in UartRxBuffer.  */
 
 } WIZFI360_HandlerTypedef;
 

STM32CubeIDE/Application/includes/wizfi360_opts.h

@@ -3,6 +3,10 @@
  *
  *  Created on: 21.05.2021
  *      Author: serca
+ *
+ *
+ *  TODO: Add Comment for wizfi360_opts.h
+ *
  */
 
 #ifndef INCLUDES_WIZFI360_OPTS_H_

STM32CubeIDE/Application/includes/wizfi360_required.h

@@ -3,6 +3,9 @@
  *
  *  Created on: 21.05.2021
  *      Author: serca
+ *
+ *  TODO: Add Comment for wizfi360_required.h
+ *
  */
 
 #ifndef INCLUDES_WIZFI360_REQUIRED_H_
@@ -12,92 +15,101 @@
 /* Target specific UART functions to be implemented -----------------------------------------*/
 
 /*
- * TODO: Comment on WIZFI360_UART_StartContinousReception
+ * @brief	Must start the UART in continous reception mode.
+ * @note	This target-specific function must be implemented by user.
  */
 extern void WIZFI360_UART_StartContinousReception();
 
 #ifdef WIZFI360_UART_TX_MODE_NON_BLOCKING
-/*
- * TODO: Comment on WIZFI360_UART_SendNonBlockingMode
+/**
+ * @brief	Must send an amount of data to WizFi360 module in interrupt mode.
+ * @note	This target-specific function must be implemented by user.
+ * @param	pData   Pointer to data buffer (u8 or u16 data elements).
+ * @param	Size    Amount of data elements (u8 or u16) to be sent.
+ * @retval	None
  */
 extern void WIZFI360_UART_SendNonBlockingMode(uint8_t* pData, uint16_t Size);
 #else
-/*
- * TODO: Comment on WIZFI360_UART_SendBlockingMode
+/**
+ * @brief	Must send an amount of data to WizFi360 module in blocking mode.
+ * @note	This target-specific function must be implemented by user.
+ * @param	pData   Pointer to data buffer (u8 or u16 data elements).
+ * @param	Size    Amount of data elements (u8 or u16) to be sent.
+ * @retval	None
  */
 extern void WIZFI360_UART_SendBlockingMode(uint8_t* pData, uint16_t Size, uint16_t Timeout);
 #endif
 
 /*********************************************************************************************/
 /* Target specific Reset functions to be implemented ----------------------------------------*/
 
-/*
- * TODO: Comment on WIZFI360_WriteResetPinLow
- */
+/**
+  * @brief 	Must set the RST pin of the module to low.
+  * @note	This target-specific function must be implemented by user.
+  * @retval None
+  */
 extern void WIZFI360_WriteResetPinLow();
 
-/*
- * TODO: Comment on WIZFI360_WriteResetPinHigh
- */
+/**
+  * @brief 	Must set the RST pin of the module to high.
+  * @note	This target-specific function must be implemented by user.
+  * @retval None
+  */
 extern void WIZFI360_WriteResetPinHigh();
 
-/*
- * TODO: Comment on WIZFI360_PreResetHard
- */
+/**
+  * @brief 	This function executes before hard-reset is performed.
+  * @note	Writing the reset pin to low could lead to errors on UART lines.
+  * 		Thus, any UART operation should be aborted and the UART reception
+  * 		should be disabled,	before resetting the wizfi360 module.
+  * @note	This target-specific function must be implemented by user.
+  * @retval None
+  */
 extern void WIZFI360_PreResetHard();
 
-/*
- * TODO: Comment on WIZFI360_PostResetHard
- */
+/**
+  * @brief 	This function executes after hard-reset is performed.
+  * @note	In this function, UART could be re-enabled, if it was disabled
+  * 		before hard-reset.
+  * @note	This target-specific function must be implemented by user.
+  * @retval None
+  */
 extern void WIZFI360_PostResetHard();
 
-/*
- * TODO: Comment on WIZFI360_Delay
- */
+/**
+  * @brief 	Must provide a delay (in milliseconds).
+  * @note	This target-specific function must be implemented by user.
+  * @param 	Delay  specifies the delay time length, in milliseconds.
+  * @retval None
+  */
 extern void WIZFI360_Delay(uint32_t Delay);
 
 /*********************************************************************************************/
 /* User specific callback functions to be implemented ---------------------------------------*/
 
+// Todo: Provide wizfi360 callback registration for user (instead of extern declaration)
+
 #ifdef WIZFI360_CALLBACK_USED_COMMAND_COMPLETE
-/*
- * TODO: Comment on WIZFI360_CommandCpltCallback
- */
 extern void WIZFI360_CommandCpltCallback(WIZFI360_CommandIdTypeDef command,
 		WIZFI360_ResponseTypeDef response);
 #endif
 
 #ifdef WIZFI360_CALLBACK_USED_WIFI_CONNECTED
-/*
- * TODO: Comment on WIZFI360_WifiConnectedCallback
- */
 extern void WIZFI360_WifiConnectedCallback();
 #endif
 
 #ifdef WIZFI360_CALLBACK_USED_WIFI_DISCONNECTED
-/*
- * TODO: Comment on WIZFI360_WifiDisconnectedCallback
- */
 extern void WIZFI360_WifiDisconnectedCallback();
 #endif
 
 #ifdef WIZFI360_CALLBACK_USED_WIFI_CONNECT_FAILED
-/*
- * TODO: Comment on WIZFI360_WifiConnectFailedCallback
- */
 extern void WIZFI360_WifiConnectFailedCallback();
 #endif
 
 #ifdef WIZFI360_CALLBACK_USED_MODULE_READY
-/*
- * TODO: Comment on WIZFI360_ModuleReadyCallback
- */
 extern void WIZFI360_ModuleReadyCallback();
 #endif
 
-/*
- * TODO: Comment on WIZFI360_RegisterSubscribeCallbacks
- */
 extern void WIZFI360_RegisterSubscribeCallbacks();
 
 /*********************************************************************************************/