--- | Loop forever, writing the buffer to file whenever a new XML
--- prologue is seen.
-loop :: Configuration -> Handle -> [String] -> IO ()
+
+-- | Loop forever, writing the @buffer@ to file whenever a
+-- \</message\> tag is seen. This is the low-level \"loop forever\"
+-- function that we stay in as long as we are connected to one feed.
+--
+-- The documentation at
+-- <http://www.sportsnetworkdata.com/feeds/xml-levels.asp> states
+-- that \<message\> will always be the root element of the XML
+-- documents, and \</message\> will be the final line transmitted
+-- for a given document. We therefore rely on this to simplify
+-- processing.
+--
+-- The bang pattern at least on @buffer@ is necessary for
+-- performance reasons.
+--
+-- We specify a timeout of fifteen minutes on the 'recv_line'
+-- function, after which we will return to our caller. This should
+-- cause the connection to be dropped, and a new one initiated. The
+-- timeout is in response to observed behavior where the feed
+-- eventually stops transmitting data entirely without closing the
+-- connection.
+--
+loop :: Configuration
+ -> Handle -- ^ Handle to the feed (network connection)
+ -> [String] -- ^ Current XML document buffer, line-by-line, in reverse
+ -> IO ()