Commenting EventIO methods

iocore/net/P_UnixNet.h

@@ -79,33 +79,55 @@ class NetEvent;
 class UnixUDPConnection;
 struct DNSConnection;
 struct NetAccept;
+
+/// Unified API for setting and clearing kernel and epoll events.
 struct EventIO {
-  int fd = -1;
+  int fd = -1; ///< file descriptor, often a system port
 #if TS_USE_KQUEUE || TS_USE_EPOLL && !defined(USE_EDGE_TRIGGER) || TS_USE_PORT
-  int events = 0;
+  int events = 0; ///< a bit mask of enabled events
 #endif
-  EventLoop event_loop = nullptr;
-  bool syscall         = true;
-  int type             = 0;
+  EventLoop event_loop = nullptr; ///< the assigned event loop
+  bool syscall         = true;    ///< if false, disable all functionality (for QUIC)
+  int type             = 0;       ///< class identifier of union data.
   union {
     Continuation *c;
     NetEvent *ne;
     DNSConnection *dnscon;
     NetAccept *na;
     UnixUDPConnection *uc;
-  } data;
+  } data; ///< a kind of continuation
+
   int start(EventLoop l, DNSConnection *vc, int events);
   int start(EventLoop l, NetAccept *vc, int events);
   int start(EventLoop l, NetEvent *ne, int events);
   int start(EventLoop l, UnixUDPConnection *vc, int events);
+  /** Setup a continuation to be called when a file descriptor is available for read or write.
+     @param l the event loop
+     @param fd file descriptor (or port)
+     @param c the continuation to call
+     @param events a mask of flags (for details `man epoll_ctl`)
+     @return int the number of events created, -1 is error
+   */
   int start(EventLoop l, int fd, Continuation *c, int events);
-  // Change the existing events by adding modify(EVENTIO_READ)
-  // or removing modify(-EVENTIO_READ), for level triggered I/O
+
+  /** Alter the events that will trigger the continuation, for level triggered I/O.
+     @param events add with positive mask(+EVENTIO_READ), or remove with negative mask (-EVENTIO_READ)
+     @return int the number of events created, -1 is error
+   */
   int modify(int events);
-  // Refresh the existing events (i.e. KQUEUE EV_CLEAR), for edge triggered I/O
+
+  /** Refresh the existing events (i.e. KQUEUE EV_CLEAR), for edge triggered I/O
+     @param events mask of events
+     @return int the number of events created, -1 is error
+   */
   int refresh(int events);
+
+  /// Remove the kernal or epoll event. Returns 0 on success.
   int stop();
+
+  /// Remove the epoll event and close the connection. Returns 0 on success.
   int close();
+
   EventIO() { data.c = nullptr; }
 };
 
@@ -506,9 +528,15 @@ check_transient_accept_error(int res)
   }
 }
 
-//
-// Disable a NetEvent
-//
+/** Disable reading on the NetEvent @a ne.
+     @param nh Nethandler that owns @a ne.
+     @param ne The @c NetEvent to modify.
+
+     - If write is already disable, also disable the inactivity timeout.
+     - clear read enabled flag.
+     - Remove the @c epoll READ flag.
+     - Take @a ne out of the read ready list.
+*/
 static inline void
 read_disable(NetHandler *nh, NetEvent *ne)
 {
@@ -521,6 +549,15 @@ read_disable(NetHandler *nh, NetEvent *ne)
   ne->ep.modify(-EVENTIO_READ);
 }
 
+/** Disable writing on the NetEvent @a ne.
+     @param nh Nethandler that owns @a ne.
+     @param ne The @c NetEvent to modify.
+
+     - If read is already disable, also disable the inactivity timeout.
+     - clear write enabled flag.
+     - Remove the @c epoll WRITE flag.
+     - Take @a ne out of the write ready list.
+*/
 static inline void
 write_disable(NetHandler *nh, NetEvent *ne)
 {