Cleanups and commenting.

Change-Id: I491a68af8614198af450942cd378c9486f27d338

src/WireDecoder.h

@@ -16,6 +16,13 @@
 
 namespace ntimpl {
 
+/* Decodes network data into native representation.
+ * This class is designed to read from a raw_istream, which provides a blocking
+ * read interface.  There are no provisions in this class for resuming a read
+ * that was interrupted partway.  Read functions return false if
+ * raw_istream.read() returned false (indicating the end of the input data
+ * stream).
+ */
 class WireDecoder {
  public:
   explicit WireDecoder(raw_istream& is, unsigned int proto_rev);
@@ -23,16 +30,25 @@ class WireDecoder {
 
   void set_proto_rev(unsigned int proto_rev) { m_proto_rev = proto_rev; }
 
+  /* Clears error indicator. */
   void Reset() { m_error = nullptr; }
 
+  /* Returns error indicator (a string describing the error).  Returns nullptr
+   * if no error has occurred.
+   */
   const char* error() const { return m_error; }
 
+  /* Reads the specified number of bytes.
+   * @param buf pointer to read data (output parameter)
+   * @param len number of bytes to read
+   */
   bool Read(char** buf, std::size_t len) {
     if (len > m_allocated) Realloc(len);
     *buf = m_buf;
     return m_is.read(m_buf, len);
   }
 
+  /* Reads a single byte. */
   bool Read8(unsigned int* val) {
     char* buf;
     if (!Read(&buf, 1)) return false;
@@ -40,6 +56,7 @@ class WireDecoder {
     return true;
   }
 
+  /* Reads a 16-bit word. */
   bool Read16(unsigned int* val) {
     char* buf;
     if (!Read(&buf, 2)) return false;
@@ -51,6 +68,7 @@ class WireDecoder {
     return true;
   }
 
+  /* Reads a 32-bit word. */
   bool Read32(unsigned long* val) {
     char* buf;
     if (!Read(&buf, 4)) return false;
@@ -68,8 +86,10 @@ class WireDecoder {
     return true;
   }
 
+  /* Reads a double. */
   bool ReadDouble(double* val);
 
+  /* Reads an ULEB128-encoded unsigned integer. */
   bool ReadUleb128(unsigned long* val) {
     return ntimpl::ReadUleb128(m_is, val);
   }
@@ -82,15 +102,23 @@ class WireDecoder {
   WireDecoder& operator=(const WireDecoder&) = delete;
 
  protected:
+  /* The protocol revision.  E.g. 0x0200 for version 2.0. */
   unsigned int m_proto_rev;
+
+  /* Error indicator. */
   const char* m_error;
 
  private:
+  /* Reallocate temporary buffer to specified length. */
   void Realloc(std::size_t len);
 
+  /* input stream */
   raw_istream& m_is;
 
+  /* temporary buffer */
   char* m_buf;
+
+  /* allocated size of temporary buffer */
   std::size_t m_allocated;
 };