polish the utility function docs

src/utils.rs

@@ -9,7 +9,7 @@ use serde_json::Value;
 use crate::error::GolgiError;
 use crate::messages::{SsbMessageKVT, SsbMessageValue};
 
-/// Function to parse an array of bytes (returned by an rpc call) into a KVT.
+/// Parse an array of bytes (returned by an rpc call) into a `KVT`.
 ///
 /// # Arguments
 ///
@@ -20,7 +20,7 @@ pub fn kvt_res_parse(body: &[u8]) -> Result<SsbMessageKVT, GolgiError> {
     Ok(kvt)
 }
 
-/// Function to parse an array of bytes (returned by an rpc call) into a String.
+/// Parse an array of bytes (returned by an rpc call) into a `String`.
 ///
 /// # Arguments
 ///
@@ -29,7 +29,7 @@ pub fn string_res_parse(body: &[u8]) -> Result<String, GolgiError> {
     Ok(std::str::from_utf8(body)?.to_string())
 }
 
-/// Function to parse an array of bytes (returned by an rpc call) into a serde_json::Value.
+/// Parse an array of bytes (returned by an rpc call) into a `serde_json::Value`.
 ///
 /// # Arguments
 ///
@@ -39,7 +39,7 @@ pub fn json_res_parse(body: &[u8]) -> Result<Value, GolgiError> {
     Ok(message)
 }
 
-/// Function to parse an array of bytes (returned by an rpc call) into an SsbMessageValue
+/// Parse an array of bytes (returned by an rpc call) into an `SsbMessageValue`.
 ///
 /// # Arguments
 ///
@@ -49,17 +49,18 @@ pub fn ssb_message_res_parse(body: &[u8]) -> Result<SsbMessageValue, GolgiError>
     Ok(message)
 }
 
-/// Takes in an rpc request number, and a handling function,
+/// Take in an RPC request number along with a handling function and wait for
-/// and waits for an rpc response which matches the request number,
+/// an RPC response which matches the request number. Then, call the handling
-/// and then calls the handling function on the response.
+/// function on the response.
 ///
 /// # Arguments
 ///
 /// * `rpc_reader` - A `RpcReader` which can return Messages in a loop
 /// * `req_no` - A `RequestNo` of the response to listen for
-/// * `f` - A function which takes in an array of u8 and returns a Result<T, GolgiError>.
+/// * `f` - A function which takes in an array of `u8` and returns a
-/// This is a function which parses the response from the RpcReader. T is a generic type,
+/// `Result<T, GolgiError>`. This is a function which parses the response from
-/// so this parse function can return multiple possible types (String, json, custom struct etc.)
+/// the `RpcReader`. `T` is a generic type, so this parse function can return
+/// multiple possible types (`String`, JSON, custom struct etc.)
 pub async fn get_async<'a, R, T, F>(
     rpc_reader: &mut RpcReader<R>,
     req_no: RequestNo,
@@ -91,19 +92,19 @@ where
     }
 }
 
-/// Takes in an rpc request number, and a handling function,
+/// Take in an RPC request number along with a handling function and call
-/// and calls the handling function on all RPC responses which match the request number,
+/// the handling function on all RPC responses which match the request number,
-/// appending the result of each parsed message to a vector,
+/// appending the result of each parsed message to a vector until a
-/// until a CancelStreamResponse is found, marking the end of the stream,
+/// `CancelStreamResponse` is found (marking the end of the stream).
-/// and then finally a result is returned.
 ///
 /// # Arguments
 ///
 /// * `rpc_reader` - A `RpcReader` which can return Messages in a loop
 /// * `req_no` - A `RequestNo` of the response to listen for
-/// * `f` - A function which takes in an array of u8 and returns a Result<T, GolgiError>.
+/// * `f` - A function which takes in an array of `u8` and returns a
-/// This is a function which parses the response from the RpcReader. T is a generic type,
+/// `Result<T, GolgiError>`. This is a function which parses the response from
-/// so this parse function can return multiple possible types (String, json, custom struct etc.)
+/// the `RpcReader`. `T` is a generic type, so this parse function can return
+/// multiple possible types (`String`, JSON, custom struct etc.)
 pub async fn get_source_until_eof<'a, R, T, F>(
     rpc_reader: &mut RpcReader<R>,
     req_no: RequestNo,
@@ -141,19 +142,20 @@ where
     Ok(messages)
 }
 
-/// Takes in an rpc request number, and a handling function,
+/// Take in an RPC request number along with a handling function and call the
-/// and calls the handling function on all responses which match the request number,
+/// handling function on all responses which match the request number. Then,
-/// and prints out the result of the handling function.
+/// prints out the result of the handling function.
 ///
-/// This is a function useful for debugging, and only prints the output.
+/// This function useful for debugging and only prints the output.
 ///
 /// # Arguments
 ///
 /// * `rpc_reader` - A `RpcReader` which can return Messages in a loop
 /// * `req_no` - A `RequestNo` of the response to listen for
-/// * `f` - A function which takes in an array of u8 and returns a Result<T, GolgiError>.
+/// * `f` - A function which takes in an array of `u8` and returns a
-/// This is a function which parses the response from the RpcReader. T is a generic type,
+/// `Result<T, GolgiError>`. This is a function which parses the response from
-/// so this parse function can return multiple possible types (String, json, custom struct etc.)
+/// the `RpcReader`. `T` is a generic type, so this parse function can return
+/// multiple possible types (`String`, JSON, custom struct etc.)
 pub async fn print_source_until_eof<'a, R, T, F>(
     rpc_reader: &mut RpcReader<R>,
     req_no: RequestNo,
@@ -183,17 +185,18 @@ where
     Ok(())
 }
 
-/// Takes in an rpc request number, and a handling function (parsing results of type T),
+/// Take in an RPC request number along with a handling function (parsing
-/// and produces an async_std::stream::Stream
+/// results of type `T`) and produce an `async_std::stream::Stream` of results
-/// of results of type T where the handling function is called
+/// of type `T`, where the handling function is called on all `RpcReader`
-/// on all rpc_reader responses which match the request number.
+/// responses which match the request number.
 ///
 /// # Arguments
 ///
 /// * `req_no` - A `RequestNo` of the response to listen for
-/// * `f` - A function which takes in an array of u8 and returns a Result<T, GolgiError>.
+/// * `f` - A function which takes in an array of `u8` and returns a
-/// This is a function which parses the response from the RpcReader. T is a generic type,
+/// `Result<T, GolgiError>`. This is a function which parses the response from
-/// so this parse function can return multiple possible types (String, json, custom struct etc.)
+/// the `RpcReader`. `T` is a generic type, so this parse function can return
+/// multiple possible types (`String`, JSON, custom struct etc.)
 pub async fn get_source_stream<'a, F, T>(
     mut rpc_reader: RpcReader<TcpStream>,
     req_no: RequestNo,