modify some annotation

utils/TcpModule/readme.md

@@ -34,10 +34,11 @@
 # 一些易混淆的点
 1. 客户端创建的套接字包含指定`目标的IP地址和端口号`（TcpClientImpl类中的init函数），服务器创建的套接字只包含`本机IP地址和监听端口`。
 
-2. 在网络编程中，服务器通常会在一个监听端口上等待来自客户端的连接请求。当服务器接受到一个连接请求时，它会创建一个新的套接字（或文件描述符）来表示这个新建立的连接，并且通常会为这个新的连接设置一系列的事件回调函数。
+2. 在网络编程中，`服务器`通常会在一个监听端口上等待来自客户端的连接请求。当服务器接受到一个连接请求时，它会创建一个新的套接字（或文件描述符）来表示这个新建立的连接（TcpClientAccept类实例），并且通常会为这个新的连接设置一系列的事件回调函数。
 
 3. 客户端实例（TcpClientImpl类对象）进行init操作时，会创建一个套接字并对目标服务器发出连接请求并启动事件循环（Loop函数），然后客户端实例会一直进行事件循环（监听是否有读写操作）直至连接关闭（Close函数）。
 
+
 # 该模块的实现过程
 ## 服务器端：
 1. 创建服务器端套接字：使用 hloop_create_tcp_server 函数创建一个新的 TCP 服务器端套接字，并指定要监听的 IP 地址和端口号。

utils/TcpModule/src/TcpServerImpl.cpp

@@ -106,8 +106,8 @@ void TcpClientAcceptImpl::Close(void)
 /**
  * @brief The server reads the data received by tcp connection.
  *
- * @param data
+ * @param data Read data content
- * @param length bytes
+ * @param length Read data byte length
  */
 void TcpClientAcceptImpl::Readed(const void *data, size_t length)
 {
@@ -134,6 +134,10 @@ ssize_t TcpClientAcceptImpl::Write(const void *data, size_t length)
     LogError("mIo is null\n");
     return TCP_MODULE_WRITE_ERROR;
 }
+/**
+ * @brief Used to perform some cleaning work or notify upper layer logic when a TCP client accepts a connection that is closed
+ * 
+ */
 void TcpClientAcceptImpl::Closed(void)
 {
     if (nullptr != mParam.mClosedFunc) {
@@ -147,6 +151,10 @@ TcpServerImpl::TcpServerImpl(const TcpServerParam param) : mParam(param)
     mLoop = nullptr;
     mIo = nullptr;
 }
+/**
+ * @brief Create an event loop to listen for connection requests from the server socket, set up relevant callback functions, and start a separate thread to run the event loop
+ * 
+ */
 void TcpServerImpl::Init(void)
 {
     constexpr int NO_FALGS = 0;
@@ -208,9 +216,9 @@ void TcpServerImpl::Loop(void)
     mLoop = nullptr;
 }
 /**
- * @brief
+ * @brief Add a newly connected client to the server connection management list.
  *
- * @param io Add the socket of the newly connected client.
+ * @param io Socket associated with server and client connections
  */
 void TcpServerImpl::AddClient(hio_t *io)
 {
@@ -223,9 +231,7 @@ void TcpServerImpl::AddClient(hio_t *io)
             SOCKADDR_STR(hio_peeraddr(io), peeraddrstr));
     std::shared_ptr<ITcpClientAccept> *addClient = NewTcpClientAccept(io, mParam.mClientAcceptParam);
     mClients[hio_fd(io)] = addClient;
-    /**
+    /// Check whether the server side accepts the connection of the client side.
-     * @brief Check whether the server side accepts the connection of the client side.
-     */
     if (mParam.mAcceptClientFunc) {
         if (mParam.mAcceptClientFunc(addClient, peeraddrstr) == true) {
             mMutex.unlock();
@@ -238,9 +244,9 @@ void TcpServerImpl::AddClient(hio_t *io)
     LogWarning("AddClient failed.\n");
 }
 /**
- * @brief
+ * @brief Retrieve the corresponding client acceptance object based on the socket handle.
  *
- * @param io socket
+ * @param io Handle pointing to socket
  * @return std::shared_ptr<ITcpClientAccept>*
  */
 std::shared_ptr<ITcpClientAccept> *TcpServerImpl::GetClient(hio_t *io)
@@ -322,7 +328,7 @@ std::shared_ptr<ITcpServer> *NewTcpServer(const TcpServerParam &param)
 }
 std::shared_ptr<ITcpClientAccept> *NewTcpClientAccept(const hio_t *io, const ClientAcceptParam &param)
 {
-    LogInfo("Create tcp server object.\n");
+    LogInfo("Create tcp client accept object.\n");
     TcpClientAccept *impl = (TcpClientAccept *)malloc(sizeof(TcpClientAccept));
     if (nullptr == impl) {
         LogError("NewTcpServer::malloc failed.\n");
@@ -331,6 +337,7 @@ std::shared_ptr<ITcpClientAccept> *NewTcpClientAccept(const hio_t *io, const Cli
     TcpClientAccept tmp;
     memcpy((void *)impl, (void *)&tmp, sizeof(TcpClientAccept));
     impl->mHeader.mCheckName = GetTcpClientAcceptName();
+    ///ObjectThis actually refers to mTcpClientAccept
     std::shared_ptr<ITcpClientAccept> *objectThis =
         (std::shared_ptr<ITcpClientAccept> *)(((char *)impl) + sizeof(ITcpServerHeader));
     impl->mTcpClientAccept = std::make_shared<TcpClientAcceptImpl>(io, objectThis, param);

utils/TcpModule/src/TcpServerImpl.h

@@ -23,8 +23,7 @@
 #include <mutex>
 #include <thread>
 /**
- * @brief The server manages the connection life cycle and data interaction of each connected client through this kind
+ * @brief The TcpClient Accept class instance is used to associate with the socket after connecting to the server and client, responsible for a series of operations (read/write, etc.) after the connection
- * of instance.
  *
  */
 class TcpClientAcceptImpl : public ITcpClientAccept, public std::enable_shared_from_this<TcpClientAcceptImpl>
@@ -32,14 +31,14 @@ class TcpClientAcceptImpl : public ITcpClientAccept, public std::enable_shared_f
 public:
     TcpClientAcceptImpl(const hio_t *io, const void *object, const ClientAcceptParam &param);
     virtual ~TcpClientAcceptImpl() = default;
-    void Close(void) override;
+    void Close(void) override;   ///<Disconnect the client
-    void Readed(const void *data, size_t length) override;
+    void Readed(const void *data, size_t length) override; ///<The server reads the data received by tcp connection.
-    ssize_t Write(const void *data, size_t length) override;
+    ssize_t Write(const void *data, size_t length) override;///<The server writes data to the tcp connection.
-    void Closed(void) override;
+    void Closed(void) override; ///<Used to perform some cleaning work or notify upper layer logic when a TCP client accepts a connection that is closed
 
 private:
-    const hio_t *mIo; /// Connected client socket
+    const hio_t *mIo; ///< Connected client socket
-    const void *mObjectThis;
+    const void *mObjectThis;///<Used to verify whether this type of instance is legal
     const ClientAcceptParam mParam;
 };
 /**
@@ -53,21 +52,21 @@ public:
     TcpServerImpl(const TcpServerParam param);
     virtual ~TcpServerImpl() = default;
     void Init(void) override;
-    void UnInit(void) override;
+    void UnInit(void) override; 
-    void Loop(void);              /// Run an event loop and release resources after completion or error.
+    void Loop(void);              ///< Run an event loop and release resources after completion or error.
-    void AddClient(hio_t *io);
+    void AddClient(hio_t *io);    ///< Add a newly connected client to the server connection management list.
-    std::shared_ptr<ITcpClientAccept> *GetClient(hio_t *io);
+    std::shared_ptr<ITcpClientAccept> *GetClient(hio_t *io);///< Retrieve the corresponding client acceptance object based on the socket handle.
-    void RemoveClient(hio_t *io); /// Remove the data element in the map, that is, the connected client.
+    void RemoveClient(hio_t *io); ///< Remove the data element in the map, that is, the connected client.
-    void FreeClients(void);       /// Clear all connected clients.
+    void FreeClients(void);       ///< Clear all connected clients.
-    void Closed(void);            /// Stop listening to the event loop(mLoop)
+    void Closed(void);            ///< Stop listening to the event loop(mLoop)
 
 private:
-    std::mutex mMutex; /// A mutex lock used to synchronize access to shared resources.
+    std::mutex mMutex; ///< A mutex lock used to synchronize access to shared resources.
-    hloop_t *mLoop;    /// Event loop, listening for all io objects
+    hloop_t *mLoop;    ///< Event loop, listening for all io objects
-    hio_t *mIo;        /// A server socket to listen whether a new client sends a connection request.
+    hio_t *mIo;        ///< A server socket to listen whether a new client sends a connection request.
     const TcpServerParam mParam;
-    std::thread mTcpServerThread;
+    std::thread mTcpServerThread;   ///< A separate thread used to run event loops
-    std::map<int, std::shared_ptr<ITcpClientAccept> *> mClients;
+    std::map<int, std::shared_ptr<ITcpClientAccept> *> mClients;///< Container for storing clients connected to servers
 };
 std::shared_ptr<ITcpServer> *NewTcpServer(const TcpServerParam &param);
 std::shared_ptr<ITcpClientAccept> *NewTcpClientAccept(const hio_t *io, const ClientAcceptParam &param);