Doxygenize MyGatewayTransport (#1023)

2018-01-01 12:13:18 +01:00
parent 292dc849cc
commit d557cb3d34
3 changed files with 94 additions and 43 deletions
@@ -17,46 +17,95 @@
 * version 2 as published by the Free Software Foundation.
 */

+/**
+* @file MyGatewayTransport.h
+*
+* @defgroup MyGatewayTransportgrp MyGatewayTransport
+* @ingroup internals
+* @{
+*
+*
+* Gateway transport-related log messages, format: [!]SYSTEM:[SUB SYSTEM:]MESSAGE
+* -[!] Exclamation mark is prepended in case of error
+* -SYSTEM:
+*  -<b>GWT</b>: messages emitted by MyGatewayTransport
+* -SUB SYSTEMS:
+*   -GWT:<b>TIN</b>		from @ref gatewayTransportInit()
+*   -GWT:<b>TPS</b>		from @ref gatewayTransportSend()
+*   -GWT:<b>RFC</b>		from _readFromClient()
+*   -GWT:<b>TSA</b>		from @ref gatewayTransportAvailable()
+*   -GWT:<b>TRC</b>		from @ref gatewayTransportReceive()
+*
+* Gateway transport debug log messages :
+*
+* |E| SYS | SUB   | Message                   | Comment
+* |-|-----|-------|---------------------------|---------------------------------------------------------------------
+* | | GWT | TIN   | CONNECTING...             | Connecting to router
+* | | GWT | TIN   | IP=%s                     | IP address obtained
+* |!| GWT | TIN   | DHCP FAIL                 | DHCP request failed
+* | | GWT | TIN   | ETH OK                    | Connected to network
+* |!| GWT | TIN   | ETH FAIL                  | Connection failed
+* | | GWT | TPS   | ETH OK                    | Connected to network
+* |!| GWT | TPS   | ETH FAIL                  | Connection failed
+* | | GWT | RFC   | C%d,MSG=%s                | Received message [%s] from client [%d]
+* |!| GWT | RFC   | C%d,MSG TOO LONG          | Received message from client [%d] too long
+* | | GWT | TSA   | UDP MSG=%s                | Received UDP message [%s]
+* | | GWT | TSA   | ETH OK                    | Connected to network
+* |!| GWT | TSA   | ETH FAIL                  | Connection failed
+* | | GWT | TSA   | C%d,DISCONNECTED          | Client [%d] disconnected
+* | | GWT | TSA   | C%d,CONNECTED             | Client [%d] connected
+* |!| GWT | TSA   | NO FREE SLOT              | No free slot for client
+* |!| GWT | TRC   | IP RENEW FAIL             | IP renewal failed
+*
+* @brief API declaration for MyGatewayTransport
+*
+*/
+
 #ifndef MyGatewayTransport_h
 #define MyGatewayTransport_h

 #include "MyProtocol.h"
 #include "MySensorsCore.h"

-#define MSG_GW_STARTUP_COMPLETE "Gateway startup complete."
+#define MSG_GW_STARTUP_COMPLETE "Gateway startup complete."		//!< Gateway startup message

-// debug output
 #if defined(MY_DEBUG_VERBOSE_GATEWAY)
-#define GATEWAY_DEBUG(x,...)	DEBUG_OUTPUT(x, ##__VA_ARGS__)	//!< debug
+#define GATEWAY_DEBUG(x,...)	DEBUG_OUTPUT(x, ##__VA_ARGS__)	//!< debug output
 #else
 #define GATEWAY_DEBUG(x,...)									//!< debug NULL
 #endif

-// Common gateway functions
-
+/**
+ * @brief Process gateway-related messages
+ */
 void gatewayTransportProcess(void);

-
-// Gateway "interface" functions
-
 /**
- * initialize the driver
+ * @brief Initialize gateway transport driver
+ * @return true if transport initialized
 */
 bool gatewayTransportInit(void);

 /**
- * Send message to controller
+ * @brief Send message to controller
+ * @param message to send
+ * @return true if message delivered
 */
 bool gatewayTransportSend(MyMessage &message);

-/*
- * Check if a new message is available from controller
+/**
+ * @brief Check if a new message is available from controller
+ * @return true if message available
 */
 bool gatewayTransportAvailable(void);

-/*
- * Pick up last message received from controller
+/**
+ * @brief Pick up last message received from controller
+ * @return message
 */
 MyMessage& gatewayTransportReceive(void);

 #endif /* MyGatewayTransportEthernet_h */
+
+/** @}*/
+