diff options
author | Matthias Beyer <mail@beyermatthias.de> | 2016-09-04 17:09:15 +0200 |
---|---|---|
committer | Matthias Beyer <mail@beyermatthias.de> | 2016-09-05 16:15:45 +0200 |
commit | 6b6e3a0e12c0e207d45027d7d83faedc9ae7984d (patch) | |
tree | 8803d18702a440d65a502690a7f970a5f26f3f40 /libimagutil | |
parent | 737aab80dc029315d412ff781f20e9afd8db55ae (diff) |
Add documentation for the code-generator macro
Diffstat (limited to 'libimagutil')
-rw-r--r-- | libimagutil/src/log_result.rs | 53 |
1 files 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 }) |