From: Amos Jeffries <squid3@treenet.co.nz>
Date: Thu, 2 Jun 2011 10:59:56 +0000 (-0600)
Subject: Cleanup: polish some code comments
X-Git-Tag: take08~55^2~154
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=27774ceec08be7e1c4969707dca0dd1d5d7a7715;p=thirdparty%2Fsquid.git

Cleanup: polish some code comments
---

diff --git a/src/client_side.h b/src/client_side.h
index 72e7aa7c2c..bcb4ccf3f4 100644
--- a/src/client_side.h
+++ b/src/client_side.h
@@ -52,6 +52,31 @@ class ClientHttpRequest;
 class clientStreamNode;
 class ChunkedCodingParser;
 
+/**
+ * Badly named.
+ * This is in fact the processing context for a single HTTP request.
+ *
+ * Managing what has been done, and what happens next to the data buffer
+ * holding what we hope is an HTTP request.
+ *
+ * Parsing is still a mess of global functions done in conjunction with the
+ * real socket controller which generated ClientHttpRequest.
+ * It also generates one of us and passes us control from there based on
+ * the results of the parse.
+ *
+ * After that all the request interpretation and adaptation is in our scope.
+ * Then finally the reply fetcher is created by this and we get the result
+ * back. Which we then have to manage writing of it to the ConnStateData.
+ *
+ * The socket level management is done by a ConnStateData which owns us.
+ * The scope of this objects control over a socket consists of the data
+ * buffer received from ConnStateData with an initially unknown length.
+ * When that length is known it sets the end bounary of our acces to the
+ * buffer.
+ *
+ * The individual processing actions are done by other Jobs which we
+ * kick off as needed.
+ */
 class ClientSocketContext : public RefCountable
 {
 
@@ -137,7 +162,20 @@ private:
 
 class ConnectionDetail;
 
-/** A connection to a socket */
+/**
+ * Manages a connection to a client.
+ *
+ * Multiple requests (up to 2) can be pipelined. This object is responsible for managing
+ * which one is currently being fulfilled and what happens to the queue if the current one
+ * causes the client connection to be closed early.
+ *
+ * Act as a manager for the connection and passes data in buffer to the current parser.
+ * the parser has ambiguous scope at present due to being made from global functions
+ * I believe this object uses the parser to identify boundaries and kick off the
+ * actual HTTP request handling objects (ClientSocketContext, ClientHttpRequest, HttpRequest)
+ *
+ * If the above can be confirmed accurate we can call this object PipelineManager or similar
+ */
 class ConnStateData : public BodyProducer, public HttpControlMsgSink
 {
 
diff --git a/src/comm.cc b/src/comm.cc
index d8227b479a..922767d409 100644
--- a/src/comm.cc
+++ b/src/comm.cc
@@ -1362,7 +1362,7 @@ comm_lingering_close(int fd)
 
 #endif
 
-/*
+/**
  * enable linger with time of 0 so that when the socket is
  * closed, TCP generates a RESET
  */
diff --git a/src/errorpage.h b/src/errorpage.h
index 26d790f513..ddc3c6d353 100644
--- a/src/errorpage.h
+++ b/src/errorpage.h
@@ -195,7 +195,7 @@ SQUIDCEXTERN void errorInitialize(void);
 SQUIDCEXTERN void errorClean(void);
 
 /**
- \ingroup ErrorPageAPI
+ * \ingroup ErrorPageAPI
  *
  * This function generates a error page from the info contained
  * by err and then sends it to the client.
diff --git a/src/neighbors.cc b/src/neighbors.cc
index 14cc40d186..492264e851 100644
--- a/src/neighbors.cc
+++ b/src/neighbors.cc
@@ -589,9 +589,9 @@ neighbors_init(void)
                 if (thisPeer->http_port != s->s.GetPort())
                     continue;
 
-                debugs(15, 1, "WARNING: Peer looks like this host");
+                debugs(15, DBG_IMPORTANT, "WARNING: Peer looks like this host");
 
-                debugs(15, 1, "         Ignoring " <<
+                debugs(15, DBG_IMPORTANT, "         Ignoring " <<
                        neighborTypeStr(thisPeer) << " " << thisPeer->host <<
                        "/" << thisPeer->http_port << "/" <<
                        thisPeer->icp.port);
@@ -603,7 +603,7 @@ neighbors_init(void)
 
     peerRefreshDNS((void *) 1);
 
-    if (ICP_INVALID == echo_hdr.opcode) {
+    if (echo_hdr.opcode == ICP_INVALID) {
         echo_hdr.opcode = ICP_SECHO;
         echo_hdr.version = ICP_VERSION_CURRENT;
         echo_hdr.length = 0;
diff --git a/src/peer_select.cc b/src/peer_select.cc
index 8715991aad..b426510077 100644
--- a/src/peer_select.cc
+++ b/src/peer_select.cc
@@ -347,10 +347,10 @@ peerSelectFoo(ps_state * ps)
     peerSelectCallback(ps);
 }
 
-/*
+/**
  * peerSelectPinned
  *
- * Selects a pinned connection
+ * Selects a pinned connection.
  */
 int peerAllowedToUse(const peer * p, HttpRequest * request);
 static void
@@ -374,7 +374,7 @@ peerSelectPinned(ps_state * ps)
     }
 }
 
-/*
+/**
  * peerGetSomeNeighbor
  *
  * Selects a neighbor (parent or sibling) based on one of the