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

Previous Next

To reply to this bug, email your comments to 41126 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Dale Mellor <guile-qf1qmg <at> rdmp.org>
To: bug-guile <bug-guile <at> gnu.org>
Subject: [PATCH] doc: Added very minimal doc strings to (srfi srfi-9 gnu).
Date: Thu, 07 May 2020 12:54:37 +0100

* 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

Message #8 received at 41126 <at> debbugs.gnu.org (full text, mbox):

From: Ludovic Courtès <ludo <at> gnu.org>
To: Dale Mellor <guile-qf1qmg <at> rdmp.org>
Cc: 41126 <at> debbugs.gnu.org
Subject: Re: bug#41126: [PATCH] doc: Added very minimal doc strings to (srfi
 srfi-9 gnu).
Date: Wed, 27 May 2020 22:21:22 +0200

Hi Dale,

Dale Mellor <guile-qf1qmg <at> rdmp.org> 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 “raw” 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-printer! (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 = #<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’.

Previous Next

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