From 1cb47c1cc86a3ee5ffdf3cf4531b4cf16641aba0 Mon Sep 17 00:00:00 2001
From: Pat Hickey <p.hickey@f5.com>
Date: Sat, 8 Feb 2025 11:18:26 -0800
Subject: [PATCH] add docs to the AsyncInputStream and AsyncOutputStream types

---
 src/io/streams.rs | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/src/io/streams.rs b/src/io/streams.rs
index bc26c12..d7139c1 100644
--- a/src/io/streams.rs
+++ b/src/io/streams.rs
@@ -3,6 +3,8 @@ use std::cell::OnceCell;
 use std::io::Result;
 use wasi::io::streams::{InputStream, OutputStream, StreamError};
 
+/// A wrapper for WASI's `InputStream` resource that provides implementations of `AsyncRead` and
+/// `AsyncPollable`.
 #[derive(Debug)]
 pub struct AsyncInputStream {
     // Lazily initialized pollable, used for lifetime of stream to check readiness.
@@ -12,12 +14,14 @@ pub struct AsyncInputStream {
 }
 
 impl AsyncInputStream {
+    /// Construct an `AsyncInputStream` from a WASI `InputStream` resource.
     pub fn new(stream: InputStream) -> Self {
         Self {
             subscription: OnceCell::new(),
             stream,
         }
     }
+    /// Await for read readiness.
     async fn ready(&self) {
         // Lazily initialize the AsyncPollable
         let subscription = self
@@ -26,7 +30,8 @@ impl AsyncInputStream {
         // Wait on readiness
         subscription.wait_for().await;
     }
-    /// Like [`AsyncRead::read`], but doesn't require a `&mut self`.
+    /// Asynchronously read from the input stream.
+    /// This method is the same as [`AsyncRead::read`], but doesn't require a `&mut self`.
     pub async fn read(&self, buf: &mut [u8]) -> Result<usize> {
         let read = loop {
             self.ready().await;
@@ -64,6 +69,8 @@ impl AsyncRead for AsyncInputStream {
     }
 }
 
+/// A wrapper for WASI's `output-stream` resource that provides implementations of `AsyncWrite` and
+/// `AsyncPollable`.
 #[derive(Debug)]
 pub struct AsyncOutputStream {
     // Lazily initialized pollable, used for lifetime of stream to check readiness.
@@ -73,12 +80,14 @@ pub struct AsyncOutputStream {
 }
 
 impl AsyncOutputStream {
+    /// Construct an `AsyncOutputStream` from a WASI `OutputStream` resource.
     pub fn new(stream: OutputStream) -> Self {
         Self {
             subscription: OnceCell::new(),
             stream,
         }
     }
+    /// Await write readiness.
     async fn ready(&self) {
         // Lazily initialize the AsyncPollable
         let subscription = self
@@ -87,7 +96,14 @@ impl AsyncOutputStream {
         // Wait on readiness
         subscription.wait_for().await;
     }
-    /// Like [`AsyncWrite::write`], but doesn't require a `&mut self`.
+    /// Asynchronously write to the output stream. This method is the same as
+    /// [`AsyncWrite::write`], but doesn't require a `&mut self`.
+    ///
+    /// Awaits for write readiness, and then performs at most one write to the
+    /// output stream. Returns how much of the argument `buf` was written, or
+    /// a `std::io::Error` indicating either an error returned by the stream write
+    /// using the debug string provided by the WASI error, or else that the,
+    /// indicated by `std::io::ErrorKind::ConnectionReset`.
     pub async fn write(&self, buf: &[u8]) -> Result<usize> {
         // Loops at most twice.
         loop {
@@ -118,7 +134,17 @@ impl AsyncOutputStream {
             }
         }
     }
-    /// Like [`AsyncWrite::flush`], but doesn't require a `&mut self`.
+    /// Asyncronously flush the output stream. Initiates a flush, and then
+    /// awaits until the flush is complete and the output stream is ready for
+    /// writing again.
+    ///
+    /// This method is the same as [`AsyncWrite::flush`], but doesn't require
+    /// a `&mut self`.
+    ///
+    /// Fails with a `std::io::Error` indicating either an error returned by
+    /// the stream flush, using the debug string provided by the WASI error,
+    /// or else that the stream is closed, indicated by
+    /// `std::io::ErrorKind::ConnectionReset`.
     pub async fn flush(&self) -> Result<()> {
         match self.stream.flush() {
             Ok(()) => {