--- Begin Message ---
|
Subject: |
[PATCH 0/3] Improve documentation for monads. |
|
Date: |
Thu, 6 Apr 2017 02:15:46 -0700 |
Hi,
The following patch series attempts to clarify how one is supposed to
use some of the monad-related syntax that Guix provides. It also
documents two commonly used forms (mwhen and munless) that were
missing from the manual.
Some of this might seem obvious to someone who is already familiar
with monads. However, since I only recently learned about monads, a
lot of these details were not obvious to me at all. For example, I
didn't know that every expression in an mbegin needs to be a monadic
expression (despite having read the manual multiple times). This was
especially confusing because the same is NOT true for an mlet. I hope
these patches will help clarify for other monad newbies how this
syntax is supposed to be used.
--
Chris
Chris Marusich (3):
monads: Use intent-revealing parameter names.
monads, doc: Improve mwhen and munless documentation.
monads: Improve mlet, mlet*, and mbegin documentation.
doc/guix.texi | 28 +++++++++++++++++++++++++---
guix/monads.scm | 36 +++++++++++++++++++++++-------------
2 files changed, 48 insertions(+), 16 deletions(-)
--
2.12.0
--- End Message ---
--- Begin Message ---
|
Subject: |
Re: bug#26382: [PATCH 3/3] monads: Improve mlet, mlet*, and mbegin documentation. |
|
Date: |
Sat, 08 Apr 2017 14:36:34 +0200 |
|
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/25.1 (gnu/linux) |
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’.
--- End Message ---