bug#26382: [PATCH 3/3] monads: Improve mlet, mlet*, and mbegin documentation.

[Chris Marusich]

* doc/guix.texi ((guix) The Store Monad) <mlet, mlet*, mbegin>: Clarify
  their intended usage.
* guix/monads.scm (mlet*, mbegin): Update docstrings accordingly.
---
 doc/guix.texi   | 14 +++++++++++---
 guix/monads.scm | 16 +++++++++++-----
 2 files changed, 22 insertions(+), 8 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index a1aae8f6c..5cd33a31d 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -4011,8 +4011,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}).
@@ -4020,7 +4027,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 fe3d5d78f..2f66f4262 100644
--- a/guix/monads.scm
+++ b/guix/monads.scm
@@ -157,9 +157,14 @@ though BIND is simply binary, as in:
 
 (define-syntax mlet*
   (syntax-rules (->)
-    "Bind the given monadic values MVAL to the given variables VAR.  When the
-form is (VAR -> VAL), bind VAR to the non-monadic value VAL in the same way as
-'let'."
+    "Bind the variables VAR to the monadic values MVAL in BODY, 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 MVAL and making VAR
+refer to that raw, non-monadic value within the scope of the BODY.  The
+form (VAR -> VAL) binds VAR to the \"normal\" value VAL, as per 'let'.  The
+binding operations occur in sequence from left to right.  The last expression
+of BODY must be a monadic expression, and its result will become the result of
+the MLET* when run in the MONAD."
     ;; Note: the '->' symbol corresponds to 'is:' in 'better-monads.rkt'.
     ((_ monad () body ...)
      (with-monad monad body ...))
@@ -185,8 +190,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 ...)
-- 
2.12.0