From 77fd78d5c9eb0dbab96a16ac5441f33a1abaa764 Mon Sep 17 00:00:00 2001
From: Adam Ierymenko <adam.ierymenko@gmail.com>
Date: Fri, 12 Jul 2013 10:13:24 -0400
Subject: [PATCH] Little cleanup and docs.

---
 node/PacketDecoder.cpp |  7 +++++--
 node/PacketDecoder.hpp | 19 ++++++++++++++++++-
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/node/PacketDecoder.cpp b/node/PacketDecoder.cpp
index 93126e16b..f7c2eef2d 100644
--- a/node/PacketDecoder.cpp
+++ b/node/PacketDecoder.cpp
@@ -51,7 +51,8 @@ bool PacketDecoder::tryDecode(const RuntimeEnvironment *_r)
 		if (_step == DECODE_STEP_WAITING_FOR_ORIGINAL_SUBMITTER_LOOKUP) {
 			// This means we've already decoded, decrypted, decompressed, and
 			// validated, and we're processing a MULTICAST_FRAME. We're waiting
-			// for a lookup on the frame's original submitter.
+			// for a lookup on the frame's original submitter. So try again and
+			// see if we have it.
 			return _doMULTICAST_FRAME(_r,peer);
 		}
 
@@ -65,7 +66,8 @@ bool PacketDecoder::tryDecode(const RuntimeEnvironment *_r)
 		} else {
 			// Unencrypted is tolerated in case we want to run this on
 			// devices where squeezing out cycles matters. HMAC is
-			// what's really important.
+			// what's really important. But log it in debug to catch any
+			// packets being mistakenly sent in the clear.
 			TRACE("ODD: %s from %s(%s) wasn't encrypted",Packet::verbString(verb()),source().toString().c_str(),_remoteAddress.toString().c_str());
 		}
 
@@ -108,6 +110,7 @@ bool PacketDecoder::tryDecode(const RuntimeEnvironment *_r)
 				return true;
 		}
 	} else {
+		_step = DECODE_STEP_WAITING_FOR_SENDER_LOOKUP;
 		_r->sw->requestWhois(source());
 		return false;
 	}
diff --git a/node/PacketDecoder.hpp b/node/PacketDecoder.hpp
index 5da8f9c09..e595d3263 100644
--- a/node/PacketDecoder.hpp
+++ b/node/PacketDecoder.hpp
@@ -50,6 +50,14 @@ class PacketDecoder : public Packet
 	friend class SharedPtr<PacketDecoder>;
 
 public:
+	/**
+	 * Create a new packet-in-decode
+	 *
+	 * @param b Source buffer with raw packet data
+	 * @param localPort Local port on which packet was received
+	 * @param remoteAddress Address from which packet came
+	 * @throws std::out_of_range Range error processing packet
+	 */
 	template<unsigned int C2>
 	PacketDecoder(const Buffer<C2> &b,Demarc::Port localPort,const InetAddress &remoteAddress)
  		throw(std::out_of_range) :
@@ -65,8 +73,15 @@ public:
 	/**
 	 * Attempt to decode this packet
 	 *
+	 * Note that this returns 'true' if processing is complete. This says nothing
+	 * about whether the packet was valid. A rejection is 'complete.'
+	 *
+	 * Once true is returned, this should not be called again.
+	 *
 	 * @param _r Runtime environment
-	 * @return True if decoding and processing is complete, false on failure (try again)
+	 * @return True if decoding and processing is complete, false if caller should try again
+	 * @throws std::out_of_range Range error processing packet (should be discarded)
+	 * @throws std::runtime_error Other error processing packet (should be discarded)
 	 */
 	bool tryDecode(const RuntimeEnvironment *_r)
 		throw(std::out_of_range,std::runtime_error);
@@ -97,6 +112,8 @@ private:
 		const SharedPtr<Peer> &p,
 		Topology::PeerVerifyResult result);
 
+	// These are called internally to handle packet contents once it has
+	// been authenticated, decrypted, decompressed, and classified.
 	bool _doERROR(const RuntimeEnvironment *_r,const SharedPtr<Peer> &peer);
 	bool _doHELLO(const RuntimeEnvironment *_r);
 	bool _doOK(const RuntimeEnvironment *_r,const SharedPtr<Peer> &peer);