docs(echo): added docs

Signed-off-by: Jad K. Haddad <jadkhaddad@gmail.com>

Author: JadKHaddad

framez/src/framed.rs

@@ -125,7 +125,50 @@ impl<'buf, C, RW> Framed<'buf, C, RW> {
         self.core.maybe_next().await
     }
 
-    /// TODO
+    /// Tries to read a frame from the underlying reader and echoes it back to the writer if the `echo` function returns `Echo::Echo`.
+    ///
+    /// # Return value
+    ///
+    /// - `Some(Ok(None))` if the buffer is not framable or the frame was echoed. Call `maybe_next_echoed` again to read more bytes.
+    /// - `Some(Ok(Some(frame)))` if a frame was successfully decoded and not echoed. Call `maybe_next_echoed` again to read more bytes.
+    /// - `Some(Err(error))` if an error occurred. The caller should stop reading.
+    /// - `None` if eof was reached. The caller should stop reading.
+    ///
+    /// # Usage
+    ///
+    /// See [`next!`](crate::next_echoed!).
+    ///
+    /// # Example
+    ///
+    /// Echo back [`str`] frames starting with a dot (`.`).
+    ///
+    /// ```rust
+    /// use core::{error::Error};
+    ///
+    /// use framez::{Echo, Framed, codec::lines::StrLines, mock::Noop, next_echoed};  
+    ///
+    /// async fn read() -> Result<(), Box<dyn Error>> {
+    ///     let r_buf = &mut [0u8; 1024];
+    ///     let w_buf = &mut [0u8; 1024];
+    ///
+    ///     let mut framed = Framed::new(StrLines::new(), Noop, r_buf, w_buf);
+    ///
+    ///     while let Some(item) = next_echoed!(framed, |item| {
+    ///         if item.starts_with('.') {
+    ///             return Echo::Echo(item);
+    ///         }
+    ///
+    ///         Echo::NoEcho(item)
+    ///     })
+    ///     .transpose()? {
+    ///         assert!(!item.starts_with('.'));
+    ///
+    ///         println!("Frame: {}", item);
+    ///     }
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
     pub async fn maybe_next_echoed<'this, F>(
         &'this mut self,
         echo: F,

framez/src/framed_core.rs

@@ -211,7 +211,9 @@ impl<'buf, C, RW> FramedCore<'buf, C, RW> {
     }
 }
 
-/// TODO
+/// Wether to echo the item back to the writer or not.
+///
+/// See [`Framed::maybe_next_echoed`](crate::Framed::maybe_next_echoed).
 #[derive(Debug)]
 pub enum Echo<T> {
     /// Echo the item back to the writer.

framez/src/lib.rs

@@ -30,7 +30,6 @@ mod framed;
 pub use framed::{Framed, FramedRead, FramedWrite};
 
 mod framed_core;
-// TODO
 pub use framed_core::Echo;
 use framed_core::FramedCore;
 

framez/src/next.rs

@@ -19,7 +19,13 @@ macro_rules! next {
     }};
 }
 
-/// TODO
+/// Calls [`Framed::maybe_next_echoed`](crate::Framed::maybe_next_echoed) in a loop until a frame is returned or an error occurs.
+///
+/// # Return value
+///
+/// - `Some(Ok(frame))` if a frame was successfully decoded or echoed. Call `next_echoed` again to read more frames.
+/// - `Some(Err(error))` if an error occurred. The caller should stop reading
+/// - `None` if eof was reached. The caller should stop reading.
 #[macro_export]
 macro_rules! next_echoed {
     ($framed:ident, $f:expr) => {{