[COMMIT seastar master] iostream: add doxygen comment for eof()

[Commit Bot]

From: Nadav Har'El <n...@scylladb.com>
Committer: Pavel Emelyanov <xe...@scylladb.com>
Branch: master

iostream: add doxygen comment for eof()

Make it clear that iostream's eof() method, just like similar functions
in other libraries (e.g., Posix's feof()), only knows that the stream is
at end-of-file after a previous attempt to read noticed the end of the
stream.

Without such a comment, some users might think that perhaps eof() is
buggy - rather than working exactly as designed. Recently there was such
a discussion in the Scylla project - see
https://github.com/scylladb/scylladb/pull/12696

Signed-off-by: Nadav Har'El <n...@scylladb.com>

Closes #1457

---
diff --git a/include/seastar/core/iostream.hh b/include/seastar/core/iostream.hh
--- a/include/seastar/core/iostream.hh
+++ b/include/seastar/core/iostream.hh
@@ -291,6 +291,11 @@ public:
template <typename Consumer>
SEASTAR_CONCEPT(requires InputStreamConsumer<Consumer, CharType> || ObsoleteInputStreamConsumer<Consumer, CharType>)
future<> consume(Consumer& c) noexcept(std::is_nothrow_move_constructible_v<Consumer>);
+ /// Returns true if the end-of-file flag is set on the stream.
+ /// Note that the eof flag is only set after a previous attempt to read
+ /// from the stream noticed the end of the stream. In other words, it is
+ /// possible that eof() returns false but read() will return an empty
+ /// buffer. Checking eof() again after the read will return true.
bool eof() const noexcept { return _eof; }
/// Returns some data from the stream, or an empty buffer on end of
/// stream.