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

[Ludovic Courtès]

Chris Marusich <address@hidden> skribis:

> * doc/guix.texi ((guix) The Store Monad) <mlet, mlet*, mbegin>: Clarify
>   their intended usage.
> * guix/monads.scm (mlet*, mbegin): Update docstrings accordingly.

[...]

> --- 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 ...))

I applied the patch but decided to leave out the hunk above so that the
docstring remains concise (I view the docstring as a helper rather than
as a reference here.)  Let me know what you think.

And yes, I agree that the fact that the body of ‘mlet’ is a regular
value whereas the body of ‘mbegin’ is a monadic value can be confusing.
Making it this way appeared to cater to the most common use cases,
though.

Thanks for improving the documentation!

Ludo’.