02/03: monads, doc: Improve mwhen and munless documentation.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 60a9fcb1377e4acc78a930904ef80b69a1c63f25
Author: Chris Marusich <address@hidden>
Date:   Thu Apr 6 02:28:35 2017 -0700

    monads, doc: Improve mwhen and munless documentation.
    
    * doc/guix.texi (The Store Monad) <mwhen, munless>: Document them.
    * guix/monads.scm (mwhen, munless): Clarify their intended use.
    
    Signed-off-by: Ludovic Courtès <address@hidden>
---
 doc/guix.texi   | 14 ++++++++++++++
 guix/monads.scm | 12 ++++++++----
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index d0f21ed..62f4483 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4054,6 +4054,20 @@ monadic expressions are ignored.  In that sense, it is 
analogous to
 @code{begin}, but applied to monadic expressions.
 @end deffn
 
address@hidden {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
+When @var{condition} is true, evaluate the sequence of monadic
+expressions @address@hidden as in an @code{mbegin}.  When
address@hidden is false, return @code{*unspecified*} in the current
+monad.  Every expression in the sequence must be a monadic expression.
address@hidden deffn
+
address@hidden {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} 
...
+When @var{condition} is false, evaluate the sequence of monadic
+expressions @address@hidden as in an @code{mbegin}.  When
address@hidden is true, return @code{*unspecified*} in the current
+monad.  Every expression in the sequence must be a monadic expression.
address@hidden deffn
+
 @cindex state monad
 The @code{(guix monads)} module provides the @dfn{state monad}, which
 allows an additional value---the state---to be @emph{threaded} through
diff --git a/guix/monads.scm b/guix/monads.scm
index 6933f7f..fe3d5d7 100644
--- a/guix/monads.scm
+++ b/guix/monads.scm
@@ -204,8 +204,10 @@ the last one."
 
 (define-syntax mwhen
   (syntax-rules ()
-    "When CONDITION is true, evaluate MEXP0..MEXP* as in an 'mbegin'.  When
-CONDITION is false, return *unspecified* in the current monad."
+    "When CONDITION is true, evaluate the sequence of monadic expressions
+MEXP0..MEXP* as in an 'mbegin'.  When CONDITION is false, return *unspecified*
+in the current monad.  Every expression in the sequence must be a monadic
+expression."
     ((_ condition mexp0 mexp* ...)
      (if condition
          (mbegin %current-monad
@@ -214,8 +216,10 @@ CONDITION is false, return *unspecified* in the current 
monad."
 
 (define-syntax munless
   (syntax-rules ()
-    "When CONDITION is false, evaluate MEXP0..MEXP* as in an 'mbegin'.  When
-CONDITION is true, return *unspecified* in the current monad."
+    "When CONDITION is false, evaluate the sequence of monadic expressions
+MEXP0..MEXP* as in an 'mbegin'.  When CONDITION is true, return *unspecified*
+in the current monad.  Every expression in the sequence must be a monadic
+expression."
     ((_ condition mexp0 mexp* ...)
      (if condition
          (return *unspecified*)