LibCore: Add documentation to Stream functions + make parameter clearer

file_size was not very clear about what it was being used for, so I
switched it to say expected_file_size to make it clear that it's just a
heuristic.

2 files changed, 10 insertions, 2 deletions

diff --git a/Userland/Libraries/LibCore/Stream.cpp b/Userland/Libraries/LibCore/Stream.cpp
index d6462efbbd..cfa6da77b4 100644
--- a/Userland/Libraries/LibCore/Stream.cpp
+++ b/Userland/Libraries/LibCore/Stream.cpp
@@ -52,7 +52,7 @@ ErrorOr<ByteBuffer> Stream::read_all(size_t block_size)
     return read_all_impl(block_size);
 }
 
-ErrorOr<ByteBuffer> Stream::read_all_impl(size_t block_size, size_t file_size)
+ErrorOr<ByteBuffer> Stream::read_all_impl(size_t block_size, size_t expected_file_size)
 {
     ByteBuffer data;
     data.ensure_capacity(file_size);
diff --git a/Userland/Libraries/LibCore/Stream.h b/Userland/Libraries/LibCore/Stream.h
index da99054337..c672440c90 100644
--- a/Userland/Libraries/LibCore/Stream.h
+++ b/Userland/Libraries/LibCore/Stream.h
@@ -37,6 +37,9 @@ public:
     /// Tries to fill the entire buffer through reading. Returns whether the
     /// buffer was filled without an error.
     virtual bool read_or_error(Bytes);
+    /// Reads the stream until EOF, storing the contents into a ByteBuffer which
+    /// is returned once EOF is encountered. The block size determines the size
+    /// of newly allocated chunks while reading.
     virtual ErrorOr<ByteBuffer> read_all(size_t block_size = 4096);
 
     virtual bool is_writable() const { return false; }
@@ -64,7 +67,12 @@ public:
     }
 
 protected:
-    ErrorOr<ByteBuffer> read_all_impl(size_t block_size, size_t file_size = 0);
+    /// Provides a default implementation of read_all that works for streams
+    /// that behave like POSIX file descriptors. expected_file_size can be
+    /// passed as a heuristic for what the Stream subclass expects the file
+    /// content size to be in order to reduce allocations (does not affect
+    /// actual reading).
+    ErrorOr<ByteBuffer> read_all_impl(size_t block_size, size_t expected_file_size = 0);
 };
 
 enum class SeekMode {