fs/io/BufferedOutputStream: add code comments

2 files changed, 23 insertions, 0 deletions

diff --git a/src/fs/io/BufferedOutputStream.cxx b/src/fs/io/BufferedOutputStream.cxx
index 7d3cd3815..2268eb50c 100644
--- a/src/fs/io/BufferedOutputStream.cxx
+++ b/src/fs/io/BufferedOutputStream.cxx
@@ -41,17 +41,22 @@ bool
 BufferedOutputStream::Write(const void *data, size_t size)
 {
 	if (gcc_unlikely(last_error.IsDefined()))
+		/* the stream has already failed */
 		return false;
 
+	/* try to append to the current buffer */
 	if (AppendToBuffer(data, size))
 		return true;
 
+	/* not enough room in the buffer - flush it */
 	if (!Flush())
 		return false;
 
+	/* see if there's now enough room */
 	if (AppendToBuffer(data, size))
 		return true;
 
+	/* too large for the buffer: direct write */
 	return os.Write(data, size, last_error);
 }
 
diff --git a/src/fs/io/BufferedOutputStream.hxx b/src/fs/io/BufferedOutputStream.hxx
index 9be4c125a..63a3f4aee 100644
--- a/src/fs/io/BufferedOutputStream.hxx
+++ b/src/fs/io/BufferedOutputStream.hxx
@@ -30,6 +30,14 @@
 class OutputStream;
 class Error;
 
+/**
+ * An #OutputStream wrapper that buffers its output to reduce the
+ * number of OutputStream::Write() calls.
+ *
+ * It simplifies error handling by managing an #Error attribute.
+ * Invoke any number of writes, and check for errors in the end using
+ * Check().
+ */
 class BufferedOutputStream {
 	OutputStream &os;
 
@@ -47,11 +55,18 @@ public:
 	gcc_printf(2,3)
 	bool Format(const char *fmt, ...);
 
+	/**
+	 * Returns false if an error has occurred.
+	 */
 	gcc_pure
 	bool Check() const {
 		return !last_error.IsDefined();
 	}
 
+	/**
+	 * Returns false if an error has occurred.  In that case, a
+	 * copy of the #Error is returned.
+	 */
 	bool Check(Error &error) const {
 		if (last_error.IsDefined()) {
 			error.Set(last_error);
@@ -60,6 +75,9 @@ public:
 			return true;
 	}
 
+	/**
+	 * Write buffer contents to the #OutputStream.
+	 */
 	bool Flush();
 
 	bool Flush(Error &error);