bug#24374: Favour docstrings for Guile functions

bug#24374: Favour docstrings for Guile functions

[Wilfred Hughes]

[-- Attachment #1.1: Type: text/plain, Size: 257 bytes --]

Guile has many well-documented functions that use docstring conventions,
but aren't actual docstrings.

This patch changes them to use proper docstrings. I've fixed a few typos,
and tweaked the wording on peek, but otherwise the documentation is
unchanged.

[-- Attachment #1.2: Type: text/html, Size: 308 bytes --]

[-- Attachment #2: 0001-Favor-docstrings-for-describing-the-purpose-of-funct.patch --]
[-- Type: text/x-patch, Size: 19887 bytes --]

From 65b1e251f0e54e2228c87227894982e700ddee89 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <me@wilfred.me.uk>
Date: Mon, 5 Sep 2016 22:23:13 -0400
Subject: [PATCH] Favor docstrings for describing the purpose of functions.

* module/ice-9/boot-9.scm: Where functions have docstring-style
  comments, make them proper docstrings.
---
 module/ice-9/boot-9.scm | 266 +++++++++++++++++++-----------------------------
 1 file changed, 103 insertions(+), 163 deletions(-)

diff --git a/module/ice-9/boot-9.scm b/module/ice-9/boot-9.scm
index 99543e7..05840d8 100644
--- a/module/ice-9/boot-9.scm
+++ b/module/ice-9/boot-9.scm
@@ -159,16 +159,13 @@ a-cont
 ;;; {Simple Debugging Tools}
 ;;;
 
-;; peek takes any number of arguments, writes them to the
-;; current ouput port, and returns the last argument.
-;; It is handy to wrap around an expression to look at
-;; a value each time is evaluated, e.g.:
-;;
-;;      (+ 10 (troublesome-fn))
-;;      => (+ 10 (pk 'troublesome-fn-returned (troublesome-fn)))
-;;
-
 (define (peek . stuff)
+  "Write arguments to the current output port, and return the last argument.
+
+This is handy for tracing function calls, e.g.:
+
+(+ 10 (troublesome-fn))
+=> (+ 10 (pk 'troublesome-fn-returned (troublesome-fn)))"
   (newline)
   (display ";;; ")
   (write stuff)
@@ -193,11 +190,11 @@ a-cont
   (if (not (memq sym *features*))
       (set! *features* (cons sym *features*))))
 
-;; Return #t iff FEATURE is available to this Guile interpreter.  In SLIB,
-;; provided? also checks to see if the module is available.  We should do that
-;; too, but don't.
+;; In SLIB, provided? also checks to see if the module is available.  We
+;; should do that too, but don't.
 
 (define (provided? feature)
+  "Return #t iff FEATURE is available to this Guile interpreter."
   (and (memq feature *features*) #t))
 
 \f
@@ -299,13 +296,10 @@ a-cont
 ;;; (or-map fn lst) is like (or (fn (car lst)) (fn (cadr lst)) (fn...) ...)
 ;;;
 
-;; and-map f l
-;;
-;; Apply f to successive elements of l until exhaustion or f returns #f.
-;; If returning early, return #f.  Otherwise, return the last value returned
-;; by f.  If f has never been called because l is empty, return #t.
-;;
 (define (and-map f lst)
+  "Apply F to successive elements of LST until exhaustion or F returns #f.
+If returning early, return #f.  Otherwise, return the last value returned
+by F.  If F has never been called because LST is empty, return #t."
   (let loop ((result #t)
              (l lst))
     (and result
@@ -313,12 +307,9 @@ a-cont
                   result)
              (loop (f (car l)) (cdr l))))))
 
-;; or-map f l
-;;
-;; Apply f to successive elements of l until exhaustion or while f returns #f.
-;; If returning early, return the return value of f.
-;;
 (define (or-map f lst)
+  "Apply F to successive elements of LST until exhaustion or while F returns #f.
+If returning early, return the return value of F."
   (let loop ((result #f)
              (l lst))
     (or result
@@ -353,9 +344,8 @@ a-cont
              (char_pred (string-ref s (1- end))))
         (string-every-c-code char_pred s start end))))
 
-;; A variant of string-fill! that we keep for compatability
-;;
 (define (substring-fill! str start end fill)
+  "A variant of string-fill! that we keep for compatibility."
   (string-fill! str fill start end))
 
 \f
@@ -1686,10 +1676,10 @@ written into the port is returned."
 ;;; {Loading by paths}
 ;;;
 
-;;; Load a Scheme source file named NAME, searching for it in the
-;;; directories listed in %load-path, and applying each of the file
-;;; name extensions listed in %load-extensions.
 (define (load-from-path name)
+  "Load a Scheme source file named NAME, searching for it in the
+directories listed in %load-path, and applying each of the file
+name extensions listed in %load-extensions."
   (start-stack 'load-stack
                (primitive-load-path name)))
 
@@ -1978,10 +1968,9 @@ written into the port is returned."
 
 ;; make-module &opt size uses binder
 ;;
-;; Create a new module, perhaps with a particular size of obarray,
-;; initial uses list, or binding procedure.
-;;
 (define* (make-module #:optional (size 31) (uses '()) (binder #f))
+  "Create a new module, perhaps with a particular size of obarray,
+initial uses list, or binding procedure."
   (if (not (integer? size))
       (error "Illegal size to make-module." size))
   (if (not (and (list? uses)
@@ -2010,15 +1999,15 @@ written into the port is returned."
   (cons module proc))
 
 (define* (module-observe-weak module observer-id #:optional (proc observer-id))
-  ;; Register PROC as an observer of MODULE under name OBSERVER-ID (which can
-  ;; be any Scheme object).  PROC is invoked and passed MODULE any time
-  ;; MODULE is modified.  PROC gets unregistered when OBSERVER-ID gets GC'd
-  ;; (thus, it is never unregistered if OBSERVER-ID is an immediate value,
-  ;; for instance).
+  "Register PROC as an observer of MODULE under name OBSERVER-ID (which can
+be any Scheme object).  PROC is invoked and passed MODULE any time
+MODULE is modified.  PROC gets unregistered when OBSERVER-ID gets GC'd
+(thus, it is never unregistered if OBSERVER-ID is an immediate value,
+for instance).
 
-  ;; The two-argument version is kept for backward compatibility: when called
-  ;; with two arguments, the observer gets unregistered when closure PROC
-  ;; gets GC'd (making it impossible to use an anonymous lambda for PROC).
+The two-argument version is kept for backward compatibility: when called
+with two arguments, the observer gets unregistered when closure PROC
+gets GC'd (making it impossible to use an anonymous lambda for PROC)."
   (hashq-set! (module-weak-observers module) observer-id proc))
 
 (define (module-unobserve token)
@@ -2082,13 +2071,10 @@ written into the port is returned."
 ;;; of M.''
 ;;;
 
-;; module-search fn m
-;;
-;; return the first non-#f result of FN applied to M and then to
-;; the modules in the uses of m, and so on recursively.  If all applications
-;; return #f, then so does this function.
-;;
 (define (module-search fn m v)
+  "Return the first non-#f result of FN applied to M and then to
+the modules in the uses of M, and so on recursively.  If all applications
+return #f, then so does this function."
   (define (loop pos)
     (and (pair? pos)
          (or (module-search fn (car pos) v)
@@ -2103,21 +2089,15 @@ written into the port is returned."
 ;;; of S in M has been set to some well-defined value.
 ;;;
 
-;; module-locally-bound? module symbol
-;;
-;; Is a symbol bound (interned and defined) locally in a given module?
-;;
 (define (module-locally-bound? m v)
+  "Is symbol V bound (interned and defined) locally in module M?"
   (let ((var (module-local-variable m v)))
     (and var
          (variable-bound? var))))
 
-;; module-bound? module symbol
-;;
-;; Is a symbol bound (interned and defined) anywhere in a given module
-;; or its uses?
-;;
 (define (module-bound? m v)
+  "Is symbol V bound (interned and defined) anywhere in module M or its
+uses?"
   (let ((var (module-variable m v)))
     (and var
          (variable-bound? var))))
@@ -2149,22 +2129,16 @@ written into the port is returned."
 (define (module-obarray-remove! ob key)
   ((if (symbol? key) hashq-remove! hash-remove!) ob key))
 
-;; module-symbol-locally-interned? module symbol
-;;
-;; is a symbol interned (not neccessarily defined) locally in a given module
-;; or its uses?  Interned symbols shadow inherited bindings even if
-;; they are not themselves bound to a defined value.
-;;
 (define (module-symbol-locally-interned? m v)
+  "Is symbol V interned (not neccessarily defined) locally in module M
+or its uses?  Interned symbols shadow inherited bindings even if they
+are not themselves bound to a defined value."
   (not (not (module-obarray-get-handle (module-obarray m) v))))
 
-;; module-symbol-interned? module symbol
-;;
-;; is a symbol interned (not neccessarily defined) anywhere in a given module
-;; or its uses?  Interned symbols shadow inherited bindings even if
-;; they are not themselves bound to a defined value.
-;;
 (define (module-symbol-interned? m v)
+  "Is symbol V interned (not neccessarily defined) anywhere in module M
+or its uses?  Interned symbols shadow inherited bindings even if they
+are not themselves bound to a defined value."
   (module-search module-symbol-locally-interned? m v))
 
 
@@ -2196,14 +2170,10 @@ written into the port is returned."
 ;;; variable is dereferenced.
 ;;;
 
-;; module-symbol-binding module symbol opt-value
-;;
-;; return the binding of a variable specified by name within
-;; a given module, signalling an error if the variable is unbound.
-;; If the OPT-VALUE is passed, then instead of signalling an error,
-;; return OPT-VALUE.
-;;
 (define (module-symbol-local-binding m v . opt-val)
+  "Return the binding of variable V specified by name within module M,
+signalling an error if the variable is unbound.  If the OPT-VALUE is
+passed, then instead of signalling an error, return OPT-VALUE."
   (let ((var (module-local-variable m v)))
     (if (and var (variable-bound? var))
         (variable-ref var)
@@ -2211,14 +2181,10 @@ written into the port is returned."
             (car opt-val)
             (error "Locally unbound variable." v)))))
 
-;; module-symbol-binding module symbol opt-value
-;;
-;; return the binding of a variable specified by name within
-;; a given module, signalling an error if the variable is unbound.
-;; If the OPT-VALUE is passed, then instead of signalling an error,
-;; return OPT-VALUE.
-;;
 (define (module-symbol-binding m v . opt-val)
+  "Return the binding of variable V specified by name within module M,
+signalling an error if the variable is unbound.  If the OPT-VALUE is
+passed, then instead of signalling an error, return OPT-VALUE."
   (let ((var (module-variable m v)))
     (if (and var (variable-bound? var))
         (variable-ref var)
@@ -2232,15 +2198,12 @@ written into the port is returned."
 ;;; {Adding Variables to Modules}
 ;;;
 
-;; module-make-local-var! module symbol
-;;
-;; ensure a variable for V in the local namespace of M.
-;; If no variable was already there, then create a new and uninitialzied
-;; variable.
-;;
 ;; This function is used in modules.c.
 ;;
 (define (module-make-local-var! m v)
+  "Ensure a variable for V in the local namespace of M.
+If no variable was already there, then create a new and uninitialized
+variable."
   (or (let ((b (module-obarray-ref (module-obarray m) v)))
         (and (variable? b)
              (begin
@@ -2254,13 +2217,10 @@ written into the port is returned."
         (module-add! m v local-var)
         local-var)))
 
-;; module-ensure-local-variable! module symbol
-;;
-;; Ensure that there is a local variable in MODULE for SYMBOL.  If
-;; there is no binding for SYMBOL, create a new uninitialized
-;; variable.  Return the local variable.
-;;
 (define (module-ensure-local-variable! module symbol)
+  "Ensure that there is a local variable in MODULE for SYMBOL.  If
+there is no binding for SYMBOL, create a new uninitialized
+variable.  Return the local variable."
   (or (module-local-variable module symbol)
       (let ((var (make-undefined-variable)))
         (module-add! module symbol var)
@@ -2268,9 +2228,8 @@ written into the port is returned."
 
 ;; module-add! module symbol var
 ;;
-;; ensure a particular variable for V in the local namespace of M.
-;;
 (define (module-add! m v var)
+  "Ensure a particular variable for V in the local namespace of M."
   (if (not (variable? var))
       (error "Bad variable to module-add!" var))
   (if (not (symbol? v))
@@ -2278,11 +2237,8 @@ written into the port is returned."
   (module-obarray-set! (module-obarray m) v var)
   (module-modified m))
 
-;; module-remove!
-;;
-;; make sure that a symbol is undefined in the local namespace of M.
-;;
 (define (module-remove! m v)
+  "Make sure that symbol V is undefined in the local namespace of M."
   (module-obarray-remove! (module-obarray m) v)
   (module-modified m))
 
@@ -2292,9 +2248,8 @@ written into the port is returned."
 
 ;; MODULE-FOR-EACH -- exported
 ;;
-;; Call PROC on each symbol in MODULE, with arguments of (SYMBOL VARIABLE).
-;;
 (define (module-for-each proc module)
+  "Call PROC on each symbol in MODULE, with arguments of (SYMBOL VARIABLE)."
   (hash-for-each proc (module-obarray module)))
 
 (define (module-map proc module)
@@ -2336,12 +2291,10 @@ written into the port is returned."
 
 ;;; {MODULE-REF -- exported}
 ;;;
-
-;; Returns the value of a variable called NAME in MODULE or any of its
-;; used modules.  If there is no such variable, then if the optional third
-;; argument DEFAULT is present, it is returned; otherwise an error is signaled.
-;;
 (define (module-ref module name . rest)
+  "Returns the value of a variable called NAME in MODULE or any of its
+used modules.  If there is no such variable, then if the optional third
+argument DEFAULT is present, it is returned; otherwise an error is signaled."
   (let ((variable (module-variable module name)))
     (if (and variable (variable-bound? variable))
         (variable-ref variable)
@@ -2352,10 +2305,9 @@ written into the port is returned."
 
 ;; MODULE-SET! -- exported
 ;;
-;; Sets the variable called NAME in MODULE (or in a module that MODULE uses)
-;; to VALUE; if there is no such variable, an error is signaled.
-;;
 (define (module-set! module name value)
+  "Sets the variable called NAME in MODULE (or in a module that MODULE uses)
+to VALUE; if there is no such variable, an error is signaled."
   (let ((variable (module-variable module name)))
     (if variable
         (variable-set! variable value)
@@ -2363,10 +2315,9 @@ written into the port is returned."
 
 ;; MODULE-DEFINE! -- exported
 ;;
-;; Sets the variable called NAME in MODULE to VALUE; if there is no such
-;; variable, it is added first.
-;;
 (define (module-define! module name value)
+  "Sets the variable called NAME in MODULE to VALUE; if there is no such
+variable, it is added first."
   (let ((variable (module-local-variable module name)))
     (if variable
         (begin
@@ -2377,18 +2328,14 @@ written into the port is returned."
 
 ;; MODULE-DEFINED? -- exported
 ;;
-;; Return #t iff NAME is defined in MODULE (or in a module that MODULE
-;; uses)
-;;
 (define (module-defined? module name)
+  "Return #t iff NAME is defined in MODULE (or in a module that MODULE
+uses)."
   (let ((variable (module-variable module name)))
     (and variable (variable-bound? variable))))
 
-;; MODULE-USE! module interface
-;;
-;; Add INTERFACE to the list of interfaces used by MODULE.
-;;
 (define (module-use! module interface)
+  "Add INTERFACE to the list of interfaces used by MODULE."
   (if (not (or (eq? module interface)
                (memq interface (module-uses module))))
       (begin
@@ -2400,12 +2347,9 @@ written into the port is returned."
         (hash-clear! (module-import-obarray module))
         (module-modified module))))
 
-;; MODULE-USE-INTERFACES! module interfaces
-;;
-;; Same as MODULE-USE!, but only notifies module observers after all
-;; interfaces are added to the inports list.
-;;
 (define (module-use-interfaces! module interfaces)
+  "Same as MODULE-USE!, but only notifies module observers after all
+interfaces are added to the inports list."
   (let* ((cur (module-uses module))
          (new (let lp ((in interfaces) (out '()))
                 (if (null? in)
@@ -2743,40 +2687,6 @@ written into the port is returned."
              (eq? (car (last-pair use-list)) the-scm-module))
         (set-module-uses! module (reverse (cdr (reverse use-list)))))))
 
-;; Return a module that is an interface to the module designated by
-;; NAME.
-;;
-;; `resolve-interface' takes four keyword arguments:
-;;
-;;   #:select SELECTION
-;;
-;; SELECTION is a list of binding-specs to be imported; A binding-spec
-;; is either a symbol or a pair of symbols (ORIG . SEEN), where ORIG
-;; is the name in the used module and SEEN is the name in the using
-;; module.  Note that SEEN is also passed through RENAMER, below.  The
-;; default is to select all bindings.  If you specify no selection but
-;; a renamer, only the bindings that already exist in the used module
-;; are made available in the interface.  Bindings that are added later
-;; are not picked up.
-;;
-;;   #:hide BINDINGS
-;;
-;; BINDINGS is a list of bindings which should not be imported.
-;;
-;;   #:prefix PREFIX
-;;
-;; PREFIX is a symbol that will be appended to each exported name.
-;; The default is to not perform any renaming.
-;;
-;;   #:renamer RENAMER
-;;
-;; RENAMER is a procedure that takes a symbol and returns its new
-;; name.  The default is not perform any renaming.
-;;
-;; Signal "no code for module" error if module name is not resolvable
-;; or its public interface is not available.  Signal "no binding"
-;; error if selected binding does not exist in the used module.
-;;
 (define* (resolve-interface name #:key
                             (select #f)
                             (hide '())
@@ -2785,6 +2695,39 @@ written into the port is returned."
                                          (symbol-prefix-proc prefix)
                                          identity))
                             version)
+  "Return a module that is an interface to the module designated by
+NAME.
+
+`resolve-interface' takes four keyword arguments:
+
+  #:select SELECTION
+
+SELECTION is a list of binding-specs to be imported; A binding-spec
+is either a symbol or a pair of symbols (ORIG . SEEN), where ORIG
+is the name in the used module and SEEN is the name in the using
+module.  Note that SEEN is also passed through RENAMER, below.  The
+default is to select all bindings.  If you specify no selection but
+a renamer, only the bindings that already exist in the used module
+are made available in the interface.  Bindings that are added later
+are not picked up.
+
+  #:hide BINDINGS
+
+BINDINGS is a list of bindings which should not be imported.
+
+  #:prefix PREFIX
+
+PREFIX is a symbol that will be appended to each exported name.
+The default is to not perform any renaming.
+
+  #:renamer RENAMER
+
+RENAMER is a procedure that takes a symbol and returns its new
+name.  The default is not perform any renaming.
+
+Signal \"no code for module\" error if module name is not resolvable
+or its public interface is not available.  Signal \"no binding\"
+error if selected binding does not exist in the used module."
   (let* ((module (resolve-module name #t version #:ensure #f))
          (public-i (and module (module-public-interface module))))
     (unless public-i
@@ -3446,12 +3389,11 @@ but it fails to load."
   (lambda formals body ...))
 
 \f
-;; Export a local variable
-
 ;; This function is called from "modules.c".  If you change it, be
 ;; sure to update "modules.c" as well.
 
 (define (module-export! m names)
+  "Export a local variable."
   (let ((public-i (module-public-interface m)))
     (for-each (lambda (name)
                 (let* ((internal-name (if (pair? name) (car name) name))
@@ -3472,9 +3414,8 @@ but it fails to load."
                   (module-add! public-i external-name var)))
               names)))
 
-;; Export all local variables from a module
-;;
 (define (module-export-all! mod)
+  "Export all local variables from a module."
   (define (fresh-interface!)
     (let ((iface (make-module)))
       (set-module-name! iface (module-name mod))
@@ -3486,9 +3427,8 @@ but it fails to load."
                    (fresh-interface!))))
     (set-module-obarray! iface (module-obarray mod))))
 
-;; Re-export a imported variable
-;;
 (define (module-re-export! m names)
+  "Re-export an imported variable."
   (let ((public-i (module-public-interface m)))
     (for-each (lambda (name)
                 (let* ((internal-name (if (pair? name) (car name) name))
-- 
2.9.3

bug#24374: Favour docstrings for Guile functions

[Andy Wingo]

On Tue 06 Sep 2016 04:34, Wilfred Hughes <me@wilfred.me.uk> writes:

> Guile has many well-documented functions that use docstring conventions, but aren't actual docstrings.
>
> This patch changes them to use proper docstrings. I've fixed a few typos, and tweaked the wording on peek, but otherwise the documentation is unchanged.

Applied.  Thank you very much!

Andy