io/BufferedOutputStream: more API documentation

src/fs/io/BufferedOutputStream.hxx

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2019 Max Kellermann <max.kellermann@gmail.com>
+ * Copyright 2014-2021 Max Kellermann <max.kellermann@gmail.com>
  *
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions
@@ -46,6 +46,9 @@ class OutputStream;
  * number of OutputStream::Write() calls.
  *
  * All wchar_t based strings are converted to UTF-8.
+ *
+ * To make sure everything is written to the underlying #OutputStream,
+ * call Flush() before destructing this object.
  */
 class BufferedOutputStream {
 	OutputStream &os;
@@ -56,27 +59,49 @@ public:
 	explicit BufferedOutputStream(OutputStream &_os) noexcept
 		:os(_os), buffer(32768) {}
 
+	/**
+	 * Write the contents of a buffer.
+	 */
 	void Write(const void *data, std::size_t size);
 
+	/**
+	 * Write the given object.  Note that this is only safe with
+	 * POD types.  Types with padding can expose sensitive data.
+	 */
 	template<typename T>
 	void WriteT(const T &value) {
 		Write(&value, sizeof(value));
 	}
 
+	/**
+	 * Write one narrow character.
+	 */
 	void Write(const char &ch) {
 		WriteT(ch);
 	}
 
+	/**
+	 * Write a null-terminated string.
+	 */
 	void Write(const char *p);
 
+	/**
+	 * Write a printf-style formatted string.
+	 */
 	gcc_printf(2,3)
 	void Format(const char *fmt, ...);
 
 #ifdef _UNICODE
+	/**
+	 * Write one narrow character.
+	 */
 	void Write(const wchar_t &ch) {
 		WriteWideToUTF8(&ch, 1);
 	}
 
+	/**
+	 * Write a null-terminated wide string.
+	 */
 	void Write(const wchar_t *p);
 #endif
 
@@ -93,6 +118,10 @@ private:
 #endif
 };
 
+/**
+ * Helper function which constructs a #BufferedOutputStream, calls the
+ * given function and flushes the #BufferedOutputStream.
+ */
 template<typename F>
 void
 WithBufferedOutputStream(OutputStream &os, F &&f)