common: document the current semantics of bl::append(std::istream)

bl::append(std::istream) comes with a surprise implementation. People may think
it would just slurp the indentical binary data from the stream. Document the
trap to let people don't mis-use it.

Signed-off-by: Robin Lee <cheeselee@fedoraproject.org>

diff --git a/src/include/buffer.h b/src/include/buffer.h
index 725dd399095f928785c305c15c9af989b391e7c1..4df15cd4aae6a7927a2867667854fb675d671d5b 100644 (file)
--- a/src/include/buffer.h
+++ b/src/include/buffer.h
@@ -1132,6 +1132,11 @@ struct error_code;
     void append(ptr&& bp);
     void append(const ptr& bp, unsigned off, unsigned len);
     void append(const list& bl);
+    /// append each non-empty line from the stream and add '\n',
+    /// so a '\n' will be added even the stream does not end with EOL.
+    ///
+    /// For example, if the stream contains "ABC\n\nDEF", "ABC\nDEF\n" is
+    /// actually appended.
     void append(std::istream& in);
     contiguous_filler append_hole(unsigned len);
     void append_zero(unsigned len);