GNU bug report logs - #41126
[PATCH] doc: Added very minimal doc strings to (srfi srfi-9 gnu).

Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.

Package: guile; Reported by: Dale Mellor <guile-qf1qmg@HIDDEN>; Keywords: patch; dated Thu, 7 May 2020 15:42:01 UTC; Maintainer for guile is bug-guile@HIDDEN.

Message received at 41126 <at> debbugs.gnu.org:


Received: (at 41126) by debbugs.gnu.org; 27 May 2020 20:21:35 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Wed May 27 16:21:35 2020
Received: from localhost ([127.0.0.1]:50046 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1je2YR-0008QC-KK
	for submit <at> debbugs.gnu.org; Wed, 27 May 2020 16:21:35 -0400
Received: from eggs.gnu.org ([209.51.188.92]:54176)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <ludo@HIDDEN>) id 1je2YM-0008Ps-72
 for 41126 <at> debbugs.gnu.org; Wed, 27 May 2020 16:21:34 -0400
Received: from fencepost.gnu.org ([2001:470:142:3::e]:44455)
 by eggs.gnu.org with esmtp (Exim 4.90_1)
 (envelope-from <ludo@HIDDEN>)
 id 1je2YG-0001X5-G8; Wed, 27 May 2020 16:21:24 -0400
Received: from [2a01:e0a:1d:7270:af76:b9b:ca24:c465] (port=37056 helo=ribbon)
 by fencepost.gnu.org with esmtpsa (TLS1.2:RSA_AES_256_CBC_SHA1:256)
 (Exim 4.82) (envelope-from <ludo@HIDDEN>)
 id 1je2YG-0007j0-0S; Wed, 27 May 2020 16:21:24 -0400
From: =?utf-8?Q?Ludovic_Court=C3=A8s?= <ludo@HIDDEN>
To: Dale Mellor <guile-qf1qmg@HIDDEN>
Subject: Re: bug#41126: [PATCH] doc: Added very minimal doc strings to (srfi
 srfi-9 gnu).
References: <781f4e51b70f51341333c0f33fa5943e1ee8149d.camel@HIDDEN>
Date: Wed, 27 May 2020 22:21:22 +0200
In-Reply-To: <781f4e51b70f51341333c0f33fa5943e1ee8149d.camel@HIDDEN> (Dale
 Mellor's message of "Thu, 07 May 2020 12:54:37 +0100")
Message-ID: <87h7w1jfi5.fsf@HIDDEN>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.3 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
X-Spam-Score: -2.3 (--)
X-Debbugs-Envelope-To: 41126
Cc: 41126 <at> debbugs.gnu.org
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -3.3 (---)

Hi Dale,

Dale Mellor <guile-qf1qmg@HIDDEN> skribis:

> * module/srfi/srfi-9/gnu.scm: Added some doc strings.

[...]

>  (define (set-record-type-printer! type proc)
> -  "Set PROC as the custom printer for TYPE."
> +  "- Scheme Procedure: set-record-type-printer! TYPE PROC
> +     Set PROC as the custom printer for TYPE."

The convention in Guile is to write docstrings like it was initially
written.  The bit you added is redundant with the function prototype,
which tools like Geiser automatically print for yourself.

At the =E2=80=9Craw=E2=80=9D REPL, you can also view that info:

--8<---------------cut here---------------start------------->8---
scheme@(guile-user)> ,a set-record-type-printer!
(srfi srfi-9 gnu): set-record-type-printer!	#<procedure set-record-type-pri=
nter! (type proc)>
scheme@(guile-user)> ,d set-record-type-printer!
Set PROC as the custom printer for TYPE.
scheme@(guile-user)> set-record-type-printer!
$9 =3D #<procedure set-record-type-printer! (type proc)>
--8<---------------cut here---------------end--------------->8---

If you wish, you can submit an updated patch that follows these
conventions.

Thank you,
Ludo=E2=80=99.




Information forwarded to bug-guile@HIDDEN:
bug#41126; Package guile. Full text available.

Message received at submit <at> debbugs.gnu.org:


Received: (at submit) by debbugs.gnu.org; 7 May 2020 15:41:29 +0000
From debbugs-submit-bounces <at> debbugs.gnu.org Thu May 07 11:41:29 2020
Received: from localhost ([127.0.0.1]:43769 helo=debbugs.gnu.org)
	by debbugs.gnu.org with esmtp (Exim 4.84_2)
	(envelope-from <debbugs-submit-bounces <at> debbugs.gnu.org>)
	id 1jWieP-0002wy-Gf
	for submit <at> debbugs.gnu.org; Thu, 07 May 2020 11:41:29 -0400
Received: from lists.gnu.org ([209.51.188.17]:38172)
 by debbugs.gnu.org with esmtp (Exim 4.84_2)
 (envelope-from <guile-qf1qmg@HIDDEN>) id 1jWf6w-0004b8-9B
 for submit <at> debbugs.gnu.org; Thu, 07 May 2020 07:54:42 -0400
Received: from eggs.gnu.org ([2001:470:142:3::10]:35438)
 by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <guile-qf1qmg@HIDDEN>)
 id 1jWf6w-0005OA-0u
 for bug-guile@HIDDEN; Thu, 07 May 2020 07:54:42 -0400
Received: from ec2-52-19-174-175.eu-west-1.compute.amazonaws.com
 ([52.19.174.175]:51364 helo=rdmp.org)
 by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)
 (Exim 4.90_1) (envelope-from <guile-qf1qmg@HIDDEN>)
 id 1jWf6v-00068c-3C
 for bug-guile@HIDDEN; Thu, 07 May 2020 07:54:41 -0400
Received: from [127.0.0.1] (helo=localhost) by rdmp.org with esmtp (Exim 4.92)
 (envelope-from <guile-qf1qmg@HIDDEN>) id 1jWf6r-00015A-T9
 for bug-guile@HIDDEN; Thu, 07 May 2020 11:54:38 +0000
Message-ID: <781f4e51b70f51341333c0f33fa5943e1ee8149d.camel@HIDDEN>
Subject: [PATCH] doc: Added very minimal doc strings to (srfi srfi-9 gnu).
From: Dale Mellor <guile-qf1qmg@HIDDEN>
To: bug-guile <bug-guile@HIDDEN>
Date: Thu, 07 May 2020 12:54:37 +0100
Organization: DM Bespoke Computer Solutions Ltd
Content-Type: text/plain; charset="UTF-8"
User-Agent: Evolution 3.30.5-1.1 
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Received-SPF: softfail client-ip=52.19.174.175;
 envelope-from=guile-qf1qmg@HIDDEN; helo=rdmp.org
X-detected-operating-system: by eggs.gnu.org: First seen = 2020/05/07 07:54:38
X-ACL-Warn: Detected OS   = ???
X-Spam_score_int: 5
X-Spam_score: 0.5
X-Spam_bar: /
X-Spam_report: (0.5 / 5.0 requ) BAYES_00=-1.9, RDNS_DYNAMIC=0.982,
 SPF_HELO_SOFTFAIL=0.732, SPF_SOFTFAIL=0.665 autolearn=_AUTOLEARN
X-Spam_action: no action
X-Spam-Score: -1.3 (-)
X-Debbugs-Envelope-To: submit
X-Mailman-Approved-At: Thu, 07 May 2020 11:41:28 -0400
X-BeenThere: debbugs-submit <at> debbugs.gnu.org
X-Mailman-Version: 2.1.18
Precedence: list
List-Id: <debbugs-submit.debbugs.gnu.org>
List-Unsubscribe: <https://debbugs.gnu.org/cgi-bin/mailman/options/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=unsubscribe>
List-Archive: <https://debbugs.gnu.org/cgi-bin/mailman/private/debbugs-submit/>
List-Post: <mailto:debbugs-submit <at> debbugs.gnu.org>
List-Help: <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=help>
List-Subscribe: <https://debbugs.gnu.org/cgi-bin/mailman/listinfo/debbugs-submit>, 
 <mailto:debbugs-submit-request <at> debbugs.gnu.org?subject=subscribe>
Errors-To: debbugs-submit-bounces <at> debbugs.gnu.org
Sender: "Debbugs-submit" <debbugs-submit-bounces <at> debbugs.gnu.org>
X-Spam-Score: -2.3 (--)


* module/srfi/srfi-9/gnu.scm: Added some doc strings.
---
 module/srfi/srfi-9/gnu.scm | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/module/srfi/srfi-9/gnu.scm b/module/srfi/srfi-9/gnu.scm
index 219bcdebb..0b9024e75 100644
--- a/module/srfi/srfi-9/gnu.scm
+++ b/module/srfi/srfi-9/gnu.scm
@@ -31,19 +31,25 @@
             set-fields))
 
 (define (set-record-type-printer! type proc)
-  "Set PROC as the custom printer for TYPE."
+  "- Scheme Procedure: set-record-type-printer! TYPE PROC
+     Set PROC as the custom printer for TYPE."
   (struct-set! type vtable-index-printer proc))
 
 (define-syntax-rule (define-immutable-record-type name ctor pred fields ...)
+  "- Scheme Procedure: define-immutable-record-type NAME CTOR PRED (FIELD GETTER [SETTER]) ..."
   ((@@ (srfi srfi-9) %define-record-type)
    #t (define-immutable-record-type name ctor pred fields ...)
    name ctor pred fields ...))
 
 (define-syntax-rule (set-field s (getter ...) expr)
+  "- Scheme Procedure: set-field RECORD (GETTER ...) EXPR
+      Set the field in RECORD with the GETTER, to the value of EXPR."
   (%set-fields #t (set-field s (getter ...) expr) ()
                s ((getter ...) expr)))
 
 (define-syntax-rule (set-fields s . rest)
+  "- Scheme Procedure: set-fields RECORD ((GETTER ...) EXPR) ...
+     Set the fields in the RECORD with the given GETTERs to the corresponding EXPRessions."
   (%set-fields #t (set-fields s . rest) ()
                s . rest))
 
-- 
2.20.1






Acknowledgement sent to Dale Mellor <guile-qf1qmg@HIDDEN>:
New bug report received and forwarded. Copy sent to bug-guile@HIDDEN. Full text available.
Report forwarded to bug-guile@HIDDEN:
bug#41126; Package guile. Full text available.
Please note: This is a static page, with minimal formatting, updated once a day.
Click here to see this page with the latest information and nicer formatting.
Last modified: Wed, 27 May 2020 20:30:02 UTC

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997 nCipher Corporation Ltd, 1994-97 Ian Jackson.