03/03: monads: Improve mlet, mlet*, and mbegin documentation.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 8bc2183fe54487793e9eb6b39ba01329671840b9
Author: Chris Marusich <address@hidden>
Date:   Thu Apr 6 02:28:36 2017 -0700

    monads: Improve mlet, mlet*, and mbegin documentation.
    
    * doc/guix.texi (The Store Monad) <mlet, mlet*, mbegin>: Clarify
    their intended usage.
    * guix/monads.scm (mbegin): Update docstring accordingly.
    
    Signed-off-by: Ludovic Courtès <address@hidden>
---
 doc/guix.texi   | 14 +++++++++++---
 guix/monads.scm |  5 +++--
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 62f4483..974d9b3 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4038,8 +4038,15 @@ in this example:
 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
        @var{body} ...
 Bind the variables @var{var} to the monadic values @var{mval} in
address@hidden  The form (@var{var} -> @var{val}) binds @var{var} to the
-``normal'' value @var{val}, as per @code{let}.
address@hidden, which is a sequence of expressions.  As with the bind
+operator, this can be thought of as ``unpacking'' the raw, non-monadic
+value ``contained'' in @var{mval} and making @var{var} refer to that
+raw, non-monadic value within the scope of the @var{body}.  The form
+(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
address@hidden, as per @code{let}.  The binding operations occur in sequence
+from left to right.  The last expression of @var{body} must be a monadic
+expression, and its result will become the result of the @code{mlet} or
address@hidden when run in the @var{monad}.
 
 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
@@ -4047,7 +4054,8 @@ Bind the variables @var{var} to the monadic values 
@var{mval} in
 
 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
 Bind @var{mexp} and the following monadic expressions in sequence,
-returning the result of the last expression.
+returning the result of the last expression.  Every expression in the
+sequence must be a monadic expression.
 
 This is akin to @code{mlet}, except that the return values of the
 monadic expressions are ignored.  In that sense, it is analogous to
diff --git a/guix/monads.scm b/guix/monads.scm
index fe3d5d7..317f85d 100644
--- a/guix/monads.scm
+++ b/guix/monads.scm
@@ -185,8 +185,9 @@ form is (VAR -> VAL), bind VAR to the non-monadic value VAL 
in the same way as
 
 (define-syntax mbegin
   (syntax-rules (%current-monad)
-    "Bind the given monadic expressions in sequence, returning the result of
-the last one."
+    "Bind MEXP and the following monadic expressions in sequence, returning
+the result of the last expression.  Every expression in the sequence must be a
+monadic expression."
     ((_ %current-monad mexp)
      mexp)
     ((_ %current-monad mexp rest ...)