add another several sentences to the macro docs

Author: cosmicexplorer

src/macros.rs

@@ -82,6 +82,15 @@ macro_rules! cfg_if {
 /// Similar to [`cfg_if`](cfg_if), but accepts a list of expressions, and generates an internal
 /// closure to return each value.
 ///
+/// The main reason this is necessary is because attaching `#[cfg(...)]` annotations to certain
+/// types of statements requires a nightly feature, or `cfg_if` would be enough on its own. This
+/// macro's restricted interface allows it to generate a closure as a circumlocution that is legal
+/// on stable rust.
+///
+/// Note that any `return` operation within the expressions provided to this macro will apply to the
+/// generated closure, not the enclosing scope--it cannot be used to interfere with external
+/// control flow.
+///
 /// The generated closure is non-[`const`](const@keyword), so cannot be used inside `const` methods.
 #[doc(hidden)]
 #[macro_export]