From 6b6e3a0e12c0e207d45027d7d83faedc9ae7984d Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Sun, 4 Sep 2016 17:09:15 +0200
Subject: [PATCH 1/4] Add documentation for the code-generator macro

---
 libimagutil/src/log_result.rs | 53 +++++++++++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/libimagutil/src/log_result.rs b/libimagutil/src/log_result.rs
index fa69ac40..95da299b 100644
--- a/libimagutil/src/log_result.rs
+++ b/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 })

From 2c89de13320addbe702d5e853e0d4bbf37a511ff Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Sun, 4 Sep 2016 17:12:54 +0200
Subject: [PATCH 2/4] Add comment for debug_result code

---
 libimagutil/src/debug_result.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libimagutil/src/debug_result.rs b/libimagutil/src/debug_result.rs
index 76ed1085..405cddd8 100644
--- a/libimagutil/src/debug_result.rs
+++ b/libimagutil/src/debug_result.rs
@@ -1,3 +1,5 @@
+// Generates a extension for the `Result<T, E>`, named `DebugResult` which has functionality to
+// print either `T` or `E` via `debug!()`.
 generate_result_logging_extension!(
     DebugResult,
     map_dbg,

From 87e170df722f61be006b386dcfd8a4d91c4ea243 Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Sun, 4 Sep 2016 17:12:54 +0200
Subject: [PATCH 3/4] Add comment for info_result code

---
 libimagutil/src/info_result.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libimagutil/src/info_result.rs b/libimagutil/src/info_result.rs
index 6b036e31..235f4f53 100644
--- a/libimagutil/src/info_result.rs
+++ b/libimagutil/src/info_result.rs
@@ -1,3 +1,5 @@
+// Generates a extension for the `Result<T, E>`, named `DebugResult` which has functionality to
+// print either `T` or `E` via `info!()`.
 generate_result_logging_extension!(
     InfoResult,
     map_info,

From ec9da007a5e0f74db7901f84a17370f9966e3e3d Mon Sep 17 00:00:00 2001
From: Matthias Beyer <mail@beyermatthias.de>
Date: Sun, 4 Sep 2016 17:12:54 +0200
Subject: [PATCH 4/4] Add comment for warn_result code

---
 libimagutil/src/warn_result.rs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/libimagutil/src/warn_result.rs b/libimagutil/src/warn_result.rs
index 505e9f40..b30e71f8 100644
--- a/libimagutil/src/warn_result.rs
+++ b/libimagutil/src/warn_result.rs
@@ -1,3 +1,5 @@
+// Generates a extension for the `Result<T, E>`, named `DebugResult` which has functionality to
+// print either `T` or `E` via `warn!()`.
 generate_result_logging_extension!(
     WarnResult,
     map_warn,