From 1a1427ce10529d4964b1419b20cb6e64fc450aa0 Mon Sep 17 00:00:00 2001
From: Niklas Keller <me@kelunik.com>
Date: Tue, 27 Jun 2017 18:35:57 +0200
Subject: [PATCH] Add explanation comments

---
 lib/BasicResolver.php   | 3 +++
 lib/Internal/Socket.php | 6 +++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/lib/BasicResolver.php b/lib/BasicResolver.php
index a3773f4..92b1109 100644
--- a/lib/BasicResolver.php
+++ b/lib/BasicResolver.php
@@ -337,10 +337,13 @@ final class BasicResolver implements Resolver {
     }
 
     private function getSocket($uri): Promise {
+        // We use a new socket for each UDP request, as that increases the entropy and mitigates response forgery.
         if (\substr($uri, 0, 3) === "udp") {
             return UdpSocket::connect($uri);
         }
 
+        // Over TCP we might reuse sockets if the server allows to keep them open. Sequence IDs in TCP are already
+        // better than a random port. Additionally, a TCP connection is more expensive.
         if (isset($this->sockets[$uri])) {
             return new Success($this->sockets[$uri]);
         }
diff --git a/lib/Internal/Socket.php b/lib/Internal/Socket.php
index 6bc4afc..3fe0720 100644
--- a/lib/Internal/Socket.php
+++ b/lib/Internal/Socket.php
@@ -26,7 +26,7 @@ abstract class Socket {
     /** @var ResourceOutputStream */
     private $output;
 
-    /** @var array */
+    /** @var array Contains already sent queries with no response yet. For UDP this is exactly zero or one item. */
     private $pending = [];
 
     /** @var MessageFactory */
@@ -35,13 +35,13 @@ abstract class Socket {
     /** @var callable */
     private $onResolve;
 
-    /** @var int */
+    /** @var int Used for determining whether the socket can be garbage collected, because it's inactive. */
     private $lastActivity;
 
     /** @var bool */
     private $receiving = false;
 
-    /** @var array */
+    /** @var array Queued requests if the number of concurrent requests is too large. */
     private $queue = [];
 
     /**