elaborate on behavior in tests where desired flow is not obvious

spec/agent_spec.rb

@@ -158,7 +158,6 @@ def wait(n=0.2)
         now = Time.now
         agent.increment("increment_test").should == 1
         agent.increment("increment_test", 5).should == 5
-        wait
       end
 
       it "should report an increment a value" do
@@ -189,6 +188,7 @@ def wait(n=0.2)
           server.commands.should     include("increment overflow_test 1 300 1")
           server.commands.should     include("increment overflow_test 2 300 1")
           server.commands.should     include("increment overflow_test 3 300 1")
+
           server.commands.should_not include("increment overflow_test 4 300 1")
           server.commands.should_not include("increment overflow_test 5 300 1")
         end
@@ -331,15 +331,18 @@ def wait(n=0.2)
         agent.increment('reconnect_test', 1, 5678) # triggers reconnect
         wait(1)
         server.connect_count.should == 2
+        # Ensure the last command sent has been received after the reconnect attempt
         server.commands.last.should == "increment reconnect_test 1 5678 1"
       end
 
       context 'not listening' do
+        # Mark server as down
         let(:listen) { false }
 
         it "should buffer commands when server is down" do
           agent.increment('reconnect_test', 1, 1234)
           wait
+          # The agent should not have sent the metric yet, the server is not responding
           agent.queue.pop(true).should include("increment reconnect_test 1 1234 1\n")
         end
 
@@ -362,46 +365,64 @@ def wait(n=0.2)
 
         it "should not be running if it cannot connect" do
           agent.gauge('connection_test', 1, 1234)
+          # nope:9999 does not resolve to anything, the agent will not resolve
+          # the address and refuse to start a worker thread
           agent.should_not be_running
         end
       end
 
       context 'not responding' do
+        # Server will not acknowledge hello or authenticate commands
         let(:response) { false }
 
         it "should buffer commands when server is not responsive" do
           agent.increment('reconnect_test', 1, 1234)
           wait
+          # Since server hasn't responded to hello or authenticate, worker thread will not send data
           agent.queue.pop(true).should include("increment reconnect_test 1 1234 1\n")
         end
       end
 
       context 'server hangup' do
         it "should cancel the worker thread when the host has hung up" do
+          # Start the background agent thread and let it send one metric successfully
           agent.gauge('connection_failure', 1, 1234)
           wait
+          # Stop the server
           server.stop
           wait
+          # Send one metric to the stopped server
           agent.gauge('connection_failure', 1, 1234)
           wait
+          # The agent thread should have stopped running since the network write would
+          # have failed. The queue will still contain the metric that has yet to be sent
           agent.should_not be_running
           agent.queue.size.should == 1
+
         end
 
-        it "should cancel the worker thread when the host has hung up" do
+        it "should restart the worker thread after hanging it up during an unreachable host event" do
+          # Start the background agent thread and let it send one metric successfully
           agent.gauge('connection_failure', 1, 1234)
           wait
+          # Stop the server
           server.stop
           wait
+          # Send one metric to the stopped server
           agent.gauge('connection_failure', 1, 1234)
           wait
+          # The agent thread should have stopped running since the network write would
+          # have failed. The queue will still contain the metric that has yet to be sent
           agent.should_not be_running
           agent.queue.size.should == 1
           wait
+          # Start the server back up again
           server.listen
           wait
+          # Sending another metric should kickstart the background worker thread
           agent.gauge('connection_failure', 1, 1234)
           wait
+          # The agent should now be running the background thread, and the queue should be empty
           agent.should be_running
           agent.queue.size.should == 0
         end
@@ -410,11 +431,13 @@ def wait(n=0.2)
 
 
       context 'not authenticating' do
+        # Server will fail all authentication attempts
         let(:authenticate) { false }
 
         it "should buffer commands when authentication fails" do
           agent.increment('reconnect_test', 1, 1234)
           wait
+          # Metrics should not have been sent since all authentication failed
           agent.queue.pop(true).should include("increment reconnect_test 1 1234 1\n")
         end
       end
@@ -423,13 +446,15 @@ def wait(n=0.2)
         it "should send commands in a short-lived process" do
           if pid = fork { agent.increment('foo', 1, 1234) }
             Process.wait(pid)
+            # The forked process should have flushed and waited on at_exit
             server.commands.last.should == "increment foo 1 1234 1"
           end
         end
 
         it "should send commands in a process that bypasses at_exit when using #cleanup" do
           if pid = fork { agent.increment('foo', 1, 1234); agent.cleanup; exit! }
             Process.wait(pid)
+            # The forked process should have flushed and waited on at_exit since cleanup was called explicitly
             server.commands.last.should == "increment foo 1 1234 1"
           end
         end