From: Alex Rousskov <rousskov@measurement-factory.com>
Date: Wed, 14 Sep 2016 21:55:19 +0000 (-0600)
Subject: Better docs for confusing actualReplyHeader()/actualRequestHeader().
X-Git-Tag: SQUID_4_0_15~41
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=501b5d24a5c0a67362b76730f76f373438573743;p=thirdparty%2Fsquid.git

Better docs for confusing actualReplyHeader()/actualRequestHeader().
---

diff --git a/src/format/Format.cc b/src/format/Format.cc
index 8e1aec6d92..d291f98b89 100644
--- a/src/format/Format.cc
+++ b/src/format/Format.cc
@@ -330,21 +330,30 @@ sslErrorName(Security::ErrorCode err, char *buf, size_t size)
 }
 #endif
 
+/// XXX: Misnamed. TODO: Split <h (and this function) to distinguish received 
+/// headers from sent headers rather than failing to distinguish requests from responses.
+/// \retval HttpReply sent to the HTTP client (access.log and default context).
+/// \retval HttpReply received (encapsulated) from the ICAP server (icap.log context).
+/// \retval HttpRequest received (encapsulated) from the ICAP server (icap.log context).
 static const HttpMsg *
 actualReplyHeader(const AccessLogEntry::Pointer &al)
 {
     const HttpMsg *msg = al->reply;
 #if USE_ADAPTATION
+    // al->icap.reqMethod is methodNone in access.log context
     if (!msg && al->icap.reqMethod == Adaptation::methodReqmod)
         msg = al->adapted_request;
 #endif
     return msg;
 }
 
+/// XXX: Misnamed. See actualReplyHeader().
+/// \return HttpRequest or HttpReply for %http::>h.
 static const HttpMsg *
 actualRequestHeader(const AccessLogEntry::Pointer &al)
 {
 #if USE_ADAPTATION
+    // al->icap.reqMethod is methodNone in access.log context
     if (al->icap.reqMethod == Adaptation::methodRespmod) {
         // XXX: for now AccessLogEntry lacks virgin response headers
         return nullptr;