docs: document stream APIs

Co-authored-by: Codex <codex@openai.com>

Author: manuzhang

src/iceberg/file_scan_task_stream.h

@@ -30,6 +30,7 @@ namespace iceberg {
 
 class FileScanTask;
 
+/// \brief Owning stream of file scan tasks.
 using FileScanTaskStream = std::unique_ptr<Stream<std::shared_ptr<FileScanTask>>>;
 
 }  // namespace iceberg

src/iceberg/manifest/manifest_reader.h

@@ -154,6 +154,7 @@ class ICEBERG_EXPORT ManifestReader {
 /// streaming.
 class ICEBERG_EXPORT SupportsManifestEntryStreaming {
  public:
+  /// \brief Destroy this streaming extension.
   virtual ~SupportsManifestEntryStreaming() = default;
 
   /// \brief Lazily read manifest entries.

src/iceberg/manifest/manifest_reader_internal.h

@@ -66,8 +66,10 @@ class ManifestReaderImpl : public ManifestReader, public SupportsManifestEntrySt
 
   Result<std::vector<ManifestEntry>> LiveEntries() override;
 
+  /// \brief Lazily read manifest entries.
   Result<ManifestEntryStream> EntriesStream() override;
 
+  /// \brief Lazily read only live (non-deleted) manifest entries.
   Result<ManifestEntryStream> LiveEntriesStream() override;
 
   ManifestReader& Select(const std::vector<std::string>& columns) override;

src/iceberg/util/stream.h

@@ -44,12 +44,22 @@ namespace iceberg {
 template <typename T>
 class Stream {
  public:
+  /// \brief Destroy this stream and release its producer resources.
   virtual ~Stream() = default;
 
+  /// \brief Construct a stream in its initial state.
   Stream() = default;
+
+  /// \brief Streams cannot be copied.
   Stream(const Stream&) = delete;
+
+  /// \brief Streams cannot be copy-assigned.
   Stream& operator=(const Stream&) = delete;
+
+  /// \brief Move a stream and its terminal state.
   Stream(Stream&&) noexcept = default;
+
+  /// \brief Move-assign a stream and its terminal state.
   Stream& operator=(Stream&&) noexcept = default;
 
   /// \brief Return the next value, or std::nullopt when the stream is exhausted.