Add documentation for the code-generator macro

libimagutil/src/log_result.rs

@@ -1,3 +1,52 @@
+/// This macro is used to generate extensions for the `Result<T, U>` type which only have
+/// sideeffects.
+///
+/// This macro is then used to generate debug/info/log/warning/etc extensions.
+///
+/// It is exported, so other crates can use it to generate more specific extensions for
+/// `Result<T, U>` types
+///
+/// # Parameters
+///
+/// The documentation for the parameters of the macro follow.
+///
+/// ## `$name`
+///
+/// name of the trait to generate
+///
+/// ## `$map_name`
+///
+/// Name of the function which is generated to call the closure with.
+///
+/// This function gets `&T` from `Result<T, E>` and can now build the argument for
+/// `$closure`. So, this function can, for example, `|e| format!("Look here: {:?}", e)`, the
+/// result gets fed to `$closure`.
+///
+/// ## `$map_str_name`
+///
+/// Name of the function which is generated to call the closure with.
+///
+/// This function gets simply a `&str` which gets fed to the `$closure` later.
+/// So it can be used to `foo().$map_str_name("Something happened")`
+///
+/// ## `$map_err_name`
+///
+/// Same as `$map_name`, but gets `&E` from `Resul<T, E>`.
+///
+/// ## `$map_err_str_name`
+///
+/// Same as `$map_str_name`, but is called for error cases in `Result<T, E>` (though no
+/// argument is passed.
+///
+/// ## `$closure`
+///
+/// The closure which should be called when mapping.
+///
+/// This closure can now do things, but the return value of the closure is discarded.
+/// So, this closure can be used for its sideeffects (logging for example) only.
+///
+/// An example would be: `|element| debug!("Element: {:?}", element)`.
+///
 #[macro_export]
 macro_rules! generate_result_logging_extension {
     {
@@ -8,7 +57,7 @@ macro_rules! generate_result_logging_extension {
         $map_err_str_name: ident,
         $closure: expr
     } => {
-        pub trait InfoResult<T, E> : Sized {
+        pub trait $name<T, E> : Sized {
 
             fn $map_name<F: FnOnce(&T) -> String>(self, f: F) -> Self;
 
@@ -24,7 +73,7 @@ macro_rules! generate_result_logging_extension {
 
         }
 
-        impl<T, E> InfoResult<T, E> for Result<T, E> {
+        impl<T, E> $name<T, E> for Result<T, E> {
 
             fn $map_name<F: FnOnce(&T) -> String>(self, f: F) -> Self {
                 self.map(|x| { $closure(f(&x)); x })