From efb658941160735e298c8b771eab021dd81612c3 Mon Sep 17 00:00:00 2001
From: Simon Tatham <anakin@pobox.com>
Date: Sat, 23 Oct 2021 18:09:25 +0100
Subject: [PATCH] Tidy up the comments in PlugVtable.

It always confused me that each comment was _after_ the function
prototype it described, instead of before, which is my usual idiom.
Reordered everything, and added a blank line between each
(comment,function) pair to make it clear what goes with what.

While I'm at it, rewrote some of the comments for clarity and whole
sentences.
---
 network.h | 50 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 18 deletions(-)

diff --git a/network.h b/network.h
index ff88923b..099895bc 100644
--- a/network.h
+++ b/network.h
@@ -52,8 +52,6 @@ typedef enum PlugLogType {
 } PlugLogType;
 
 struct PlugVtable {
-    void (*log)(Plug *p, PlugLogType type, SockAddr *addr, int port,
-                const char *error_msg, int error_code);
     /*
      * Passes the client progress reports on the process of setting
      * up the connection.
@@ -86,13 +84,26 @@ struct PlugVtable {
      * all Plugs must implement this method, even if only to ignore
      * the logged events.
      */
-    void (*closing)
-     (Plug *p, const char *error_msg, int error_code);
-    /* error_msg is NULL iff it is not an error (ie it closed normally) */
-    /* calling_back != 0 iff there is a Plug function */
-    /* currently running (would cure the fixme in try_send()) */
-    void (*receive) (Plug *p, int urgent, const char *data, size_t len);
+    void (*log)(Plug *p, PlugLogType type, SockAddr *addr, int port,
+                const char *error_msg, int error_code);
+
     /*
+     * Notifies the Plug that the socket is closing.
+     *
+     * For a normal non-error close, error_msg is NULL. If the socket
+     * has encountered an error, error_msg will contain a string
+     * (ownership not transferred), and error_code will contain the OS
+     * error code, if available.
+     *
+     * OS error codes will vary between platforms, of course, but
+     * platform.h should define any that we need to distinguish here,
+     * in particular BROKEN_PIPE_ERROR_CODE.
+     */
+    void (*closing)(Plug *p, const char *error_msg, int error_code);
+
+    /*
+     * Provides incoming socket data to the Plug. Three cases:
+     *
      *  - urgent==0. `data' points to `len' bytes of perfectly
      *    ordinary data.
      *
@@ -102,19 +113,22 @@ struct PlugVtable {
      *  - urgent==2. `data' points to `len' bytes of data,
      *    the first of which was the one at the Urgent mark.
      */
-    void (*sent) (Plug *p, size_t bufsize);
+    void (*receive) (Plug *p, int urgent, const char *data, size_t len);
+
     /*
-     * The `sent' function is called when the pending send backlog
-     * on a socket is cleared or partially cleared. The new backlog
-     * size is passed in the `bufsize' parameter.
+     * Called when the pending send backlog on a socket is cleared or
+     * partially cleared. The new backlog size is passed in the
+     * `bufsize' parameter.
+     */
+    void (*sent) (Plug *p, size_t bufsize);
+
+    /*
+     * Only called on listener-type sockets, and is passed a
+     * constructor function+context that will create a fresh Socket
+     * describing the connection. It returns nonzero if it doesn't
+     * want the connection for some reason, or 0 on success.
      */
     int (*accepting)(Plug *p, accept_fn_t constructor, accept_ctx_t ctx);
-    /*
-     * `accepting' is called only on listener-type sockets, and is
-     * passed a constructor function+context that will create a fresh
-     * Socket describing the connection. It returns nonzero if it
-     * doesn't want the connection for some reason, or 0 on success.
-     */
 };
 
 /* Proxy indirection layer.