From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:42329) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1cwpc3-0008A8-RS for guix-patches@gnu.org; Sat, 08 Apr 2017 08:37:08 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1cwpby-0006z1-Tk for guix-patches@gnu.org; Sat, 08 Apr 2017 08:37:07 -0400 Received: from debbugs.gnu.org ([208.118.235.43]:38985) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1cwpby-0006yo-Qg for guix-patches@gnu.org; Sat, 08 Apr 2017 08:37:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1cwpby-0005Sp-Kr for guix-patches@gnu.org; Sat, 08 Apr 2017 08:37:02 -0400 Subject: bug#26382: [PATCH 3/3] monads: Improve mlet, mlet*, and mbegin documentation. Resent-To: guix-patches@gnu.org Resent-Message-ID: From: ludo@gnu.org (Ludovic =?UTF-8?Q?Court=C3=A8s?=) References: <20170406091546.24107-1-cmmarusich@gmail.com> <20170406092836.24766-1-cmmarusich@gmail.com> <20170406092836.24766-3-cmmarusich@gmail.com> Date: Sat, 08 Apr 2017 14:36:34 +0200 In-Reply-To: <20170406092836.24766-3-cmmarusich@gmail.com> (Chris Marusich's message of "Thu, 6 Apr 2017 02:28:36 -0700") Message-ID: <87o9w7qdnx.fsf@gnu.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: Chris Marusich Cc: 26382-done@debbugs.gnu.org Chris Marusich skribis: > * doc/guix.texi ((guix) The Store Monad) : 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: >=20=20 > (define-syntax mlet* > (syntax-rules (->) > - "Bind the given monadic values MVAL to the given variables VAR. Whe= n 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 makin= g 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 expre= ssion > +of BODY must be a monadic expression, and its result will become the res= ult 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 =E2=80=98mlet=E2=80=99 is a= regular value whereas the body of =E2=80=98mbegin=E2=80=99 is a monadic value can b= e confusing. Making it this way appeared to cater to the most common use cases, though. Thanks for improving the documentation! Ludo=E2=80=99.