Document macros

src/macros.rs

@@ -1,4 +1,23 @@
-/// Unwrap a Result, and log the error.
+/// Unwrap a Result. If it's Err then log the error and provided format string
+/// and return.
+///
+/// # Arguments
+///
+/// * `$e:expr` : Expression to evaluate, must return `Result<T, Box<dyn Error>>`
+/// * `$($arg:tt)*` : Format string and parameters (like `println!()`)
+///
+/// # Example
+///
+/// ```
+/// use std::fs::File;
+/// use rude::result::RudeResult;
+/// use rude::try_log;
+///
+/// fn main() -> RudeResult<()> {
+///     let file = try_log!(File::open(file!()), "Unable to open {}", file!());
+///     Ok(())
+/// }
+/// ```
 #[macro_export]
 macro_rules! try_log {
 	($e:expr, $($arg:tt)*) => {
@@ -13,7 +32,26 @@ macro_rules! try_log {
 	};
 }
 
-/// Unwrap a Result and print if it's an error
+/// Unwrap a Result. If it's Err then print the error and provided format string
+/// and return.
+///
+/// # Arguments
+///
+/// * `$e:expr` : Expression to evaluate, must return `Result<T, Box<dyn Error>>`
+/// * `$($arg:tt)*` : Format string and parameters (like `println!()`)
+///
+/// # Example
+///
+/// ```
+/// use std::fs::File;
+/// use rude::result::RudeResult;
+/// use rude::try_print;
+///
+/// fn main() -> RudeResult<()> {
+///     let file = try_print!(File::open(file!()), "Unable to open {}", file!());
+///     Ok(())
+/// }
+/// ```
 #[macro_export]
 macro_rules! try_print {
 	($e:expr, $($arg:tt)*) => {
@@ -28,7 +66,30 @@ macro_rules! try_print {
 	};
 }
 
-/// Unwrap a `Result<T, E>`, if it's an error then let client know and return.
+/// Unwrap a Result. If it's Err then print the error and return a generic
+/// error message for the client.
+///
+/// # Arguments
+///
+/// * `$i:ident` : mio::Token to designate the client
+/// * `$e:expr` : Expression to evaluate, must return `Result<T, Box<dyn Error>>`
+///
+/// # Example
+///
+/// ```
+/// use std::fs::File;
+/// use mio::Token;
+/// use rude::queue::SendQueue;
+/// use rude::try_send_error;
+///
+/// fn check_file() -> SendQueue {
+///     let token = Token(12);
+///     let file = try_send_error!(token, File::open(file!()));
+///     SendQueue::ok(token)
+/// }
+///
+/// # assert_eq!(check_file().0[0].1, SendQueue::ok(Token(12)).0[0].1);
+/// ```
 #[macro_export]
 macro_rules! try_send_error {
 	($i:ident, $e:expr) => {
@@ -41,39 +102,113 @@ macro_rules! try_send_error {
 					line!(),
 					e
 				);
-				return SendQueue::error($i);
+				return $crate::queue::SendQueue::error($i);
 				}
 			}
 	};
 }
 
-/// Unwrap a `Result<T, E>`, send a message if it's E.
+/// Unwrap a `Result` and return a custom message to send to the client for Err.
+///
+/// # Arguments
+///
+/// * `$i:ident` : `mio::Token` client identifier
+/// * `$e:expr` : Expression to evaluate, must return `Result<T, Box<dyn Error>>`
+/// * `$($arg:tt)*` : Format string and parameters (like `println!()`)
+///
+/// # Example
+///
+/// ```
+/// use std::fs::File;
+/// use mio::Token;
+/// use rude::queue::SendQueue;
+/// use rude::try_send;
+///
+/// fn check_file() -> SendQueue {
+///     let token = Token(12);
+///     let file = try_send!(token, File::open(file!()), "Unable to open {}", file!());
+///     SendQueue::ok(token)
+/// }
+///
+/// # assert_eq!(check_file().0[0].1, SendQueue::ok(Token(12)).0[0].1);
+/// ```
 #[macro_export]
 macro_rules! try_send {
 	($i:ident, $e:expr, $($arg:tt)*) => {
 		match $e {
 			Ok(r) => r,
 			Err(_e) => {
-				return SendQueue(vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into());
+				return $crate::queue::SendQueue(
+					vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into()
+				);
 			}
 		}
 	};
 }
 
-/// Unwrap a `Option<T>`, send a message if it's None.
+/// Unarap an `Option` and return a custom message for the client if it is None.
+///
+/// # Arguments
+///
+/// * `$i:ident` : `mio::Token` client identifier
+/// * `$e:expr` : Expression to evaluate, must return `Option<T>`
+/// * `$($arg:tt)*` : Format string and parameters (like `println!()`)
+///
+/// # Example
+///
+/// ```
+/// use mio::Token;
+/// use rude::queue::SendQueue;
+/// use rude::option_send;
+///
+/// fn check_file() -> SendQueue {
+///     let token = Token(12);
+///     let option = Some(4);
+///     let send = option_send!(token, option, "Option unwrapped to None");
+///     SendQueue::ok(token)
+/// }
+///
+/// # assert_eq!(check_file().0[0].1, SendQueue::ok(Token(12)).0[0].1);
+/// ```
 #[macro_export]
 macro_rules! option_send {
 	($i:ident, $e:expr, $($arg:tt)*) => {
 		match $e {
 			Some(r) => r,
 			None => {
-				return SendQueue(vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into());
+				return $crate::queue::SendQueue(
+					vec![($i, std::fmt::format(format_args!($($arg)*)), true)].into()
+				);
 			}
 		}
 	};
 }
 
-/// Unwrap a `Result<Option<T>, E>`, log message if it's error or none
+/// Unwrap a `Result<Option<T>, E>` and for Err or None, log a message and send
+/// a generic error message to the client.
+///
+/// # Arguments
+///
+/// * `$i:ident` : `mio::Token` client identifier
+/// * `$e:expr` : Expression to evaluate, must return `Result<T, Box<dyn Error>>`
+///
+/// # Example
+///
+/// ```
+/// use std::error::Error;
+/// use mio::Token;
+/// use rude::queue::SendQueue;
+/// use rude::try_option_send_error;
+///
+/// fn tor() -> SendQueue {
+///     let token = Token(12);
+///     let tor: Result<Option<usize>, Box<dyn Error>> = Ok(Some(42));
+///     let file = try_option_send_error!(token, tor);
+///     SendQueue::ok(token)
+/// }
+///
+/// # assert_eq!(tor().0[0].1, SendQueue::ok(Token(12)).0[0].1);
+/// ```
 #[macro_export]
 macro_rules! try_option_send_error {
 	($i:ident, $e:expr) => {
@@ -85,7 +220,7 @@ macro_rules! try_option_send_error {
 					file!(),
 					line!()
 				);
-				return SendQueue::error($i);
+				return $crate::queue::SendQueue::error($i);
 				}
 			Err(e) => {
 				log::error!(
@@ -94,19 +229,8 @@ macro_rules! try_option_send_error {
 					line!(),
 					e
 				);
-				return SendQueue::error($i);
+				return $crate::queue::SendQueue::error($i);
 				}
 			}
 	};
 }
-
-// #[macro_export]
-// macro_rules! try_option_send_error {
-// 	($i:ident, $e:expr) => {
-// 		if let Ok(Some(r)) = $e {
-// 				r
-// 		} else {
-// 			return SendQueue::error($i);
-// 			}
-// 	};
-// }