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.
From 65b1e251f0e54e2228c87227894982e700ddee89 Mon Sep 17 00:00:00 2001
From: Wilfred Hughes
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))
@@ -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))
@@ -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
