--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2007-04-27  Eric Blake  <ebb9@byu.net>
 
+	* lib/freading.h: Improve comments.
+	* lib/fwriting.h: Likewise.
+	* lib/fflush.c: Likewise.
+
 	Fix closein for mingw.
 	* modules/closein-tests: Add tests for closein.
 	* tests/test-closein.c: New file.

--- a/lib/fflush.c
+++ b/lib/fflush.c
@@ -46,11 +46,13 @@
      recent operation was not input", POSIX and C99 requires that fflush
      writes out any buffered data, and all implementations do this.
 
-     When stream is, however, an input stream or an update stream in which
-     the most recent operation was input, POSIX and C99 specify nothing.
-     mingw, in particular, drops the input buffer, leaving the file descriptor
-     positioned at the end of the input buffer. I.e. ftell (stream) is lost.
-     We don't want to call the implementation's fflush in this case.
+     When stream is, however, an input stream or an update stream in
+     which the most recent operation was input, C99 specifies nothing,
+     and POSIX only specifies behavior if the stream is seekable.
+     mingw, in particular, drops the input buffer, leaving the file
+     descriptor positioned at the end of the input buffer. I.e. ftell
+     (stream) is lost.  We don't want to call the implementation's
+     fflush in this case.
 
      We test ! freading (stream) here, rather than fwriting (stream), because
      what we need to know is whether the stream holds a "read buffer", and on
@@ -59,7 +61,8 @@
     return fflush (stream);
 
   /* POSIX does not specify fflush behavior for non-seekable input
-     streams.  */
+     streams.  Some implementations purge unread data, some return
+     EBADF, some do nothing.  */
   pos = ftello (stream);
   if (pos == -1)
     {
@@ -79,7 +82,7 @@
     return EOF;
   /* After a successful lseek, update the file descriptor's position cache
      in the stream.  */
-#if defined __sferror               /* FreeBSD, NetBSD, OpenBSD, MacOS X, Cygwin */
+#if defined __sferror           /* FreeBSD, NetBSD, OpenBSD, MacOS X, Cygwin */
   stream->_offset = pos;
   stream->_flags |= __SOFF;
 #endif

--- a/lib/freading.h
+++ b/lib/freading.h
@@ -18,10 +18,17 @@
 #include <stdbool.h>
 #include <stdio.h>
 
-/* Return true if the stream STREAM is opened read-only, or if the last
-   operation on the stream was a read operation.  Return false if the stream
-   supports writing and the last operation on it was a write operation or
-   there was no such operation.
+/* Return true if the stream STREAM is opened read-only, or if the
+   last operation on the stream was a read operation.  Return false if
+   the stream is opened write-only or append-only, or if it supports
+   writing and there is no current read operation (such as fputc).
+
+   freading and fwriting will never both be true.  If STREAM supports
+   both reads and writes, then both freading and fwriting might be
+   false when the stream is first opened, after repositioning (such as
+   fseek, fsetpos, or rewind), after read encounters EOF, or after
+   fflush, depending on the underlying implementation.
+
    STREAM must not be wide-character oriented.  */
 
 #if HAVE___FREADING && !defined __GLIBC__ /* Solaris >= 7, not glibc >= 2.2  */

--- a/lib/fwriting.h
+++ b/lib/fwriting.h
@@ -18,10 +18,18 @@
 #include <stdbool.h>
 #include <stdio.h>
 
-/* Return true if the stream STREAM is opened write-only or append-only, or
-   if the last operation on the stream was a write operation.  Return false
-   if the stream supports reading and the last operation on it was a read
-   operation or there was no such operation.
+/* Return true if the stream STREAM is opened write-only or
+   append-only, or if the last operation on the stream was a write
+   operation.  Return false if the stream is opened read-only, or if
+   it supports reading and there is no current write operation (such
+   as fputc).
+
+   freading and fwriting will never both be true.  If STREAM supports
+   both reads and writes, then both freading and fwriting might be
+   false when the stream is first opened, after repositioning (such as
+   fseek, fsetpos, or rewind), after read encounters EOF, or after
+   fflush, depending on the underlying implementation.
+
    STREAM must not be wide-character oriented.  */
 
 #if HAVE___FWRITING /* glibc >= 2.2, Solaris >= 7 */