guile/guile-core/ice-9 documentation.scm

[Thien-Thi Nguyen]

CVSROOT:        /cvs
Module name:    guile
Changes by:     Thien-Thi Nguyen <address@hidden>       01/05/18 09:30:59

Modified files:
        guile-core/ice-9: documentation.scm 

Log message:
        Fix documentation for Guile Documentation Format Version 2:
        Mention required terminating newlines.
        
        (find-documentation): Delete.
        (search-documentation-files): New proc, exported.
        (object-documentation): Use `search-documentation-files'.

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/guile/guile-core/ice-9/documentation.scm.diff?cvsroot=OldCVS&tr1=1.4&tr2=1.5&r1=text&r2=text

Patches:
Index: guile/guile-core/ice-9/documentation.scm
diff -u guile/guile-core/ice-9/documentation.scm:1.4 
guile/guile-core/ice-9/documentation.scm:1.5
--- guile/guile-core/ice-9/documentation.scm:1.4        Fri Apr 27 17:28:58 2001
+++ guile/guile-core/ice-9/documentation.scm    Fri May 18 09:30:59 2001
@@ -25,6 +25,12 @@
 ;; documentation-files  -- a search-list of files using the Guile
 ;;                         Documentation Format Version 2.
 ;;
+;; search-documentation-files -- a procedure that takes NAME (a symbol)
+;;                               and searches `documentation-files' for
+;;                               associated documentation.  optional
+;;                               arg FILES is a list of filenames to use
+;;                               instead of `documentation-files'.
+;;
 ;; object-documentation -- a procedure that returns its arg's docstring
 ;;
 ;; * Guile Documentation Format
@@ -35,14 +41,17 @@
 ;; HEADER
 ;; ^LPROC1
 ;; DOCUMENTATION1
+;;
 ;; ^LPROC2
 ;; DOCUMENTATION2
-;; ...
+;;
+;; ^L...
 ;;
 ;; The HEADER is completely ignored.  The "^L" are formfeeds.  PROC1, PROC2
 ;; and so on are symbols that name the element documented.  DOCUMENTATION1,
 ;; DOCUMENTATION2 and so on are the related documentation, w/o any further
-;; formatting.
+;; formatting.  Note that there are two newlines before the next formfeed;
+;; these are discarded when the documentation is read in.
 ;;
 ;; (Version 1, corresponding to guile-1.4 and prior, is documented as being
 ;; not documented anywhere except by this embarrassingly circular comment.)
@@ -72,7 +81,9 @@
 
 (define-module (ice-9 documentation)
   :use-module (ice-9 rdelim)
-  :export (file-commentary documentation-files object-documentation)
+  :export (file-commentary
+           documentation-files search-documentation-files
+           object-documentation)
   :autoload (ice-9 regex) (match:suffix)
   :no-backtrace)
 
@@ -137,11 +148,6 @@
             %site-dir
             (lambda () "."))))
 
-(define (find-documentation name)
-  (or-map (lambda (file)
-           (find-documentation-in-file name file))
-          documentation-files))
-
 (define entry-delimiter "\f")
 
 (define (find-documentation-in-file name file)
@@ -163,6 +169,12 @@
                    (substring entry (+ len 2) (- (string-length entry) 2)))
                   (else (loop (read-delimited entry-delimiter port)))))))))
 
+(define (search-documentation-files name . files)
+  (or-map (lambda (file)
+           (find-documentation-in-file name file))
+          (cond ((null? files) documentation-files)
+                (else files))))
+
 ;; helper until the procedure documentation property is cleaned up
 (define (proc-doc proc)
   (or (procedure-documentation proc)
@@ -179,11 +191,11 @@
             (and transformer
                  (proc-doc transformer))))
       (object-property object 'documentation)
-      ;; find-documentation currently only works for builtin primitives
       (and (procedure? object)
           (not (closure? object))
           (procedure-name object)
-          (let ((docstring (find-documentation (procedure-name object))))
+          (let ((docstring (search-documentation-files
+                             (procedure-name object))))
             (if docstring
                 (set-procedure-property! object 'documentation docstring))
             docstring))))