Add comments in public header files (#100)

Author: an-tao

trantor/net/Channel.h

@@ -1,7 +1,7 @@
 /**
  *
- *  Channel.h
- *  An Tao
+ *  @file Channel.h
+ *  @author An Tao
  *
  *  Public header file in trantor lib.
  *

trantor/net/EventLoop.h

@@ -41,13 +41,38 @@ enum
     InvalidTimerId = 0
 };
 
+/**
+ * @brief As the name implies, this class represents an event loop that runs in
+ * a perticular thread. The event loop can handle network I/O events and timers
+ * in asynchronous mode.
+ * @note An event loop object always belongs to a separate thread, and there is
+ * one event loop object at most in a thread. We can call an event loop object
+ * the event loop of the thread it belongs to, or call that thread the thread of
+ * the event loop.
+ */
 class EventLoop : NonCopyable
 {
   public:
     EventLoop();
     ~EventLoop();
+
+    /**
+     * @brief Run the event loop. This method will be blocked until the event
+     * loop exits.
+     *
+     */
     void loop();
+
+    /**
+     * @brief Let the event loop quit.
+     *
+     */
     void quit();
+
+    /**
+     * @brief Assertion that the current thread is the thread to which the event
+     * loop belongs. If the assertion fails, the program aborts.
+     */
     void assertInLoopThread()
     {
         if (!isInLoopThread())
@@ -56,47 +81,82 @@ class EventLoop : NonCopyable
         }
     };
 #ifdef __linux__
+    /**
+     * @brief Make the timer queue works after calling the fork() function.
+     *
+     */
     void resetTimerQueue();
 #endif
+    /**
+     * @brief Make the event loop works after calling the fork() function.
+     *
+     */
     void resetAfterFork();
+
+    /**
+     * @brief Return true if the current thread is the thread to which the event
+     * loop belongs.
+     *
+     * @return true
+     * @return false
+     */
     bool isInLoopThread() const
     {
         return threadId_ == std::this_thread::get_id();
     };
+
+    /**
+     * @brief Get the event loop of the current thread. Return nullptr if there
+     * is no event loop in the current thread.
+     *
+     * @return EventLoop*
+     */
     static EventLoop *getEventLoopOfCurrentThread();
-    void updateChannel(Channel *chl);
-    void removeChannel(Channel *chl);
+
+    /**
+     * @brief Run the function f in the thread of the event loop.
+     *
+     * @param f
+     * @note If the current thread is the thread of the event loop, the function
+     * f is executed directly before the method exiting.
+     */
     void runInLoop(const Func &f);
     void runInLoop(Func &&f);
+
+    /**
+     * @brief Run the function f in the thread of the event loop.
+     *
+     * @param f
+     * @note The difference between this method and the runInLoop() method is
+     * that the function f is executed after the method exiting no matter if the
+     * current thread is the thread of the event loop.
+     */
     void queueInLoop(const Func &f);
     void queueInLoop(Func &&f);
-    void wakeup();
-    void wakeupRead();
-    size_t index()
-    {
-        return index_;
-    }
-    void setIndex(size_t index)
-    {
-        index_ = index;
-    }
 
-    ///
-    /// Runs callback at 'time'.
-    /// Safe to call from other threads.
-    ///
+    /**
+     * @brief Run a function at a time point.
+     *
+     * @param time The time to run the function.
+     * @param cb The function to run.
+     * @return TimerId The ID of the timer.
+     */
     TimerId runAt(const Date &time, const Func &cb);
     TimerId runAt(const Date &time, Func &&cb);
-    ///
-    /// Runs callback after @c delay seconds.
-    /// Safe to call from other threads.
-    ///
+
+    /**
+     * @brief Run a function after a period of time.
+     *
+     * @param delay Represent the period of time in seconds.
+     * @param cb The function to run.
+     * @return TimerId The ID of the timer.
+     */
     TimerId runAfter(double delay, const Func &cb);
     TimerId runAfter(double delay, Func &&cb);
 
-    /// Runs @param cb after @param delay
     /**
-     * Users could use chrono literals to represent a time duration
+     * @brief Run a function after a period of time.
+     * @note Users could use chrono literals to represent a time duration
      * For example:
      * @code
        runAfter(5s, task);
@@ -112,15 +172,19 @@ class EventLoop : NonCopyable
     {
         return runAfter(delay.count(), std::move(cb));
     }
-    ///
-    /// Runs callback every @c interval seconds.
-    /// Safe to call from other threads.
-    ///
+
+    /**
+     * @brief Repeatedly run a function every period of time.
+     *
+     * @param interval The duration in seconds.
+     * @param cb The function to run.
+     * @return TimerId The ID of the timer.
+     */
     TimerId runEvery(double interval, const Func &cb);
     TimerId runEvery(double interval, Func &&cb);
 
-    /// Runs @param cb every @param interval time
     /**
+     * @brief Repeatedly run a function every period of time.
      * Users could use chrono literals to represent a time duration
      * For example:
      * @code
@@ -139,27 +203,82 @@ class EventLoop : NonCopyable
     {
         return runEvery(interval.count(), std::move(cb));
     }
-    // int getAioEventFd();
-    // io_context_t getAioContext() {return ctx_;};
+
+    /**
+     * @brief Invalidate the timer identified by the given ID.
+     *
+     * @param id The ID of the timer.
+     */
     void invalidateTimer(TimerId id);
 
+    /**
+     * @brief Move the EventLoop to the current thread, this method must be
+     * called before the loop is running.
+     *
+     */
+    void moveToCurrentThread();
+
+    /**
+     * @brief Update channel status. This method is usually used internally.
+     *
+     * @param chl
+     */
+    void updateChannel(Channel *chl);
+
+    /**
+     * @brief Remove a channel from the event loop. This method is usually used
+     * internally.
+     *
+     * @param chl
+     */
+    void removeChannel(Channel *chl);
+
+    /**
+     * @brief Return the index of the event loop.
+     *
+     * @return size_t
+     */
+    size_t index()
+    {
+        return index_;
+    }
+
+    /**
+     * @brief Set the index of the event loop.
+     *
+     * @param index
+     */
+    void setIndex(size_t index)
+    {
+        index_ = index;
+    }
+
+    /**
+     * @brief Return true if the event loop is running.
+     *
+     * @return true
+     * @return false
+     */
     bool isRunning()
     {
         return looping_ && (!quit_);
     }
+
+    /**
+     * @brief Check if the event loop is calling a function.
+     *
+     * @return true
+     * @return false
+     */
     bool isCallingFunctions()
     {
         return callingFuncs_;
     }
-    /**
-     * @brief Move the EventLoop to the current thread, this method must be
-     * called before the loop is running.
-     *
-     */
-    void moveToCurrentThread();
 
   private:
     void abortNotInLoopThread();
+    void wakeup();
+    void wakeupRead();
     bool looping_;
     std::thread::id threadId_;
     bool quit_;

trantor/net/EventLoopThread.h

@@ -1,7 +1,7 @@
 /**
  *
- *  EventLoopThread.h
- *  An Tao
+ *  @file EventLoopThread.h
+ *  @author An Tao
  *
  *  Public header file in trantor lib.
  *
@@ -24,16 +24,37 @@
 
 namespace trantor
 {
+/**
+ * @brief This class represents an event loop thread.
+ *
+ */
 class EventLoopThread : NonCopyable
 {
   public:
     explicit EventLoopThread(const std::string &threadName = "EventLoopThread");
     ~EventLoopThread();
+
+    /**
+     * @brief Wait for the event loop to exit.
+     * @note This method blocks the current thread until the event loop exits.
+     */
     void wait();
+
+    /**
+     * @brief Get the pointer of the event loop of the thread.
+     *
+     * @return EventLoop*
+     */
     EventLoop *getLoop() const
     {
         return loop_;
     }
+
+    /**
+     * @brief Run the event loop of the thread. This method doesn't block the
+     * current thread.
+     *
+     */
     void run();
 
   private:

trantor/net/EventLoopThreadPool.h

@@ -1,7 +1,7 @@
 /**
  *
- *  EventLoopThreadPool.h
- *  An Tao
+ *  @file EventLoopThreadPool.h
+ *  @author An Tao
  *
  *  Public header file in trantor lib.
  *
@@ -20,21 +20,68 @@
 
 namespace trantor
 {
+/**
+ * @brief This class represents a pool of EventLoopThread objects
+ *
+ */
 class EventLoopThreadPool : NonCopyable
 {
   public:
     EventLoopThreadPool() = delete;
+
+    /**
+     * @brief Construct a new event loop thread pool instance.
+     *
+     * @param threadNum The number of threads
+     * @param name The name of the EventLoopThreadPool object.
+     */
     EventLoopThreadPool(size_t threadNum,
                         const std::string &name = "EventLoopThreadPool");
+
+    /**
+     * @brief Run all event loops in the pool.
+     * @note This function doesn't block the current thread.
+     */
     void start();
-    // void stop();
+
+    /**
+     * @brief Wait for all event loops in the pool to quit.
+     *
+     * @note This function blocks the current thread.
+     */
     void wait();
+
+    /**
+     * @brief Return the number of the event loop.
+     *
+     * @return size_t
+     */
     size_t size()
     {
         return loopThreadVector_.size();
     }
+
+    /**
+     * @brief Get the next event loop in the pool.
+     *
+     * @return EventLoop*
+     */
     EventLoop *getNextLoop();
+
+    /**
+     * @brief Get the event loop in the `id` position in the pool.
+     *
+     * @param id The id of the first event loop is zero. If the id >= the number
+     * of event loops, nullptr is returned.
+     * @return EventLoop*
+     */
     EventLoop *getLoop(size_t id);
+
+    /**
+     * @brief Get all event loops in the pool.
+     *
+     * @return std::vector<EventLoop *>
+     */
     std::vector<EventLoop *> getLoops() const;
 
   private: