add comments around TCP buffering

daemon/io.c

@@ -224,7 +224,8 @@ static void tcp_recv(uv_stream_t *handle, ssize_t nread, const uv_buf_t *buf)
 				uv_timer_start(&s->timeout, tcp_timeout_trigger, 1, KR_CONN_RTT_MAX/2);
 			}
 		}
-	/* Connection spawned more than one request, reset its deadline for next query. */
+	/* Connection spawned at least one request, reset its deadline for next query.
+	 * https://tools.ietf.org/html/rfc7766#section-6.2.3 */
 	} else if (ret > 0 && !s->outgoing) {
 		uv_timer_again(&s->timeout);
 	}

daemon/io.h

@@ -31,7 +31,7 @@ struct session {
 	bool throttled;
 	bool has_tls;
 	uv_timer_t timeout;
-	struct qr_task *buffering;
+	struct qr_task *buffering; /**< Worker buffers the incomplete TCP query here. */
 	struct tls_ctx_t *tls_ctx;
 	array_t(struct qr_task *) tasks;
 };

daemon/tls.h

@@ -46,7 +46,9 @@ void tls_free(struct tls_ctx_t* tls);
 /*! Push new data to TLS context for sending */
 int tls_push(struct qr_task *task, uv_handle_t* handle, knot_pkt_t * pkt);
 
-/*! Unwrap incoming data from a TLS stream and pass them to TCP session. */
+/*! Unwrap incoming data from a TLS stream and pass them to TCP session.
+ * @return the number of newly-completed requests (>=0) or an error code
+ */
 int tls_process(struct worker_ctx *worker, uv_stream_t *handle, const uint8_t *buf, ssize_t nread);
 
 /*! Set TLS certificate and key from files. */

daemon/worker.h

@@ -41,7 +41,7 @@ int worker_submit(struct worker_ctx *worker, uv_handle_t *handle, knot_pkt_t *qu
  * Process incoming DNS/TCP message fragment(s).
  * If the fragment contains only a partial message, it is buffered.
  * If the fragment contains a complete query or completes current fragment, execute it.
- * @return 0 or an error code
+ * @return the number of newly-completed requests (>=0) or an error code
  */
 int worker_process_tcp(struct worker_ctx *worker, uv_stream_t *handle,
 		const uint8_t *msg, ssize_t len);