add more comments

4 files changed, 47 insertions, 2 deletions

diff --git a/vespalib/src/vespa/vespalib/data/input.h b/vespalib/src/vespa/vespalib/data/input.h
index 7e97d98e9e1..db70857a775 100644
--- a/vespalib/src/vespa/vespalib/data/input.h
+++ b/vespalib/src/vespa/vespalib/data/input.h
@@ -14,7 +14,8 @@ namespace vespalib {
 struct Input
 {
     /**
-     * Obtain more input data.
+     * Obtain more input data. An empty Memory should be returned if
+     * and only if all input data has been exhausted.
      *
      * @return the obtained input data
      **/
diff --git a/vespalib/src/vespa/vespalib/data/input_reader.h b/vespalib/src/vespa/vespalib/data/input_reader.h
index 65345a94e19..3d01eaffca0 100644
--- a/vespalib/src/vespa/vespalib/data/input_reader.h
+++ b/vespalib/src/vespa/vespalib/data/input_reader.h
@@ -43,6 +43,13 @@ public:
 
     void fail(const vespalib::string &msg);
 
+    /**
+     * Make sure we have more input data available.
+     *
+     * @return number of bytes available without requesting more from
+     *         the underlying Input. Returns 0 if and only is there is
+     *         no more input data available.
+     **/
     size_t obtain() {
         if (__builtin_expect(_pos < _data.size, true)) {                    
             return size();
@@ -50,6 +57,13 @@ public:
         return obtain_slow();
     }
 
+    /**
+     * Read a single byte. Reading past the end of the input will
+     * result in the reader failing with input underflow.
+     *
+     * @return the next input byte. Returns 0 if the reader has
+     *         failed.
+     **/
     char read() {
         if (__builtin_expect(obtain() > 0, true)) {
             return _data.data[_pos++];
@@ -57,6 +71,17 @@ public:
         return 0;
     }
 
+    /**
+     * Read a continous sequence of bytes. Bytes within an input chunk
+     * will be referenced directly. Reads crossing chunk boundries
+     * will result in a gathering copy into a temporary buffer owned
+     * by the reader itself. Reading past the end of the input will
+     * result in the reader failing with input underflow.
+     *
+     * @param bytes the number of bytes we want to read
+     * @return Memory referencing the read bytes. Returns an empty
+     *         Memory if the reader has failed.
+     **/
     Memory read(size_t bytes) {
         if (__builtin_expect(obtain() >= bytes, true)) {
             Memory ret(data(), bytes);
diff --git a/vespalib/src/vespa/vespalib/data/output.h b/vespalib/src/vespa/vespalib/data/output.h
index 89f40e5543c..eed1419de96 100644
--- a/vespalib/src/vespa/vespalib/data/output.h
+++ b/vespalib/src/vespa/vespalib/data/output.h
@@ -14,7 +14,8 @@ namespace vespalib {
 struct Output
 {
     /**
-     * Reserve space for more output data.
+     * Reserve space for more output data. The returned WritableMemory
+     * must contain at least the requested number of bytes.
      *
      * @return the reserved output data
      * @param bytes number of bytes to reserve
diff --git a/vespalib/src/vespa/vespalib/data/output_writer.h b/vespalib/src/vespa/vespalib/data/output_writer.h
index e5fd8101677..1e9db9b29fa 100644
--- a/vespalib/src/vespa/vespalib/data/output_writer.h
+++ b/vespalib/src/vespa/vespalib/data/output_writer.h
@@ -27,6 +27,16 @@ public:
         : _output(output), _data(), _pos(0), _chunk_size(chunk_size) {}
     ~OutputWriter();
 
+    /**
+     * Reserve the requested number of bytes in the output and return
+     * a pointer to the first one. You must call the commit function
+     * after writing the bytes to make them part of the output. All
+     * other writer operations will invalidate the pointer returned
+     * from this function.
+     *
+     * @param the number of bytes to reserve
+     * @return pointer to reserved bytes
+     **/
     char *reserve(size_t bytes) {
         if (__builtin_expect((_pos + bytes) <= _data.size, true)) {
             return (_data.data + _pos);
@@ -34,6 +44,14 @@ public:
         return reserve_slow(bytes);
     }
 
+    /**
+     * Commit bytes written to a memory region previously returned by
+     * the reserve function. You must never commit more bytes than you
+     * reserved. You should never commit bytes that are not written
+     * (their values will be undefined).
+     *
+     * @param bytes the number of bytes to commit
+     **/
     void commit(size_t bytes) {
         _pos += bytes;
     }