* ports.c (scm_drain_input): extended the docstring. thanks to

	Alex Schroeder and Thien-Thi Nguyen.

diff --git a/libguile/ChangeLog b/libguile/ChangeLog
index e17b83c..df99c73 100644 (file)
--- a/libguile/ChangeLog
+++ b/libguile/ChangeLog
@@ -1,3 +1,8 @@
+2001-09-25  Gary Houston  <ghouston@arglist.com>
+
+       * ports.c (scm_drain_input): extended the docstring.  thanks to
+       Alex Schroeder and Thien-Thi Nguyen.
+
 2001-09-23  Mikael Djurfeldt  <mdj@linnaeus>
 
        * validate.h (SCM_NUM2FLOAT, SCM_NUM2DOUBLE,

diff --git a/libguile/ports.c b/libguile/ports.c
index 4ee18fc..9e1acad 100644 (file)
--- a/libguile/ports.c
+++ b/libguile/ports.c
@@ -311,8 +311,19 @@ size_t scm_take_from_input_buffers (SCM port, char *dest, size_t read_len)
 /* Clear a port's read buffers, returning the contents.  */
 SCM_DEFINE (scm_drain_input, "drain-input", 1, 0, 0, 
             (SCM port),
-           "Drain @var{port}'s read buffers (including any pushed-back\n"
-           "characters) and return the content as a single string.")
+           "This procedure clears a port's input buffers, similar\n"
+           "to the way that force-output clears the output buffer.  The\n"
+           "contents of the buffers are returned as a single string, e.g.,\n"
+           "\n"
+           "@lisp\n"
+           "(define p (open-input-file ...))\n"
+           "(drain-input p) => empty string, nothing buffered yet.\n"
+           "(unread-char (read-char p) p)\n"
+           "(drain-input p) => initial chars from p, up to the buffer size.\n"
+           "@end lisp\n\n"
+           "Draining the buffers may be useful for cleanly finishing\n"
+           "buffered I/O so that the file descriptor can be used directly\n"
+           "for further input.")
 #define FUNC_NAME s_scm_drain_input
 {
   SCM result;