* lib/freading.h: Improve comments.

* lib/fwriting.h: Likewise.
* lib/fflush.c: Likewise.

1 files changed, 11 insertions, 4 deletions

diff --git a/lib/freading.h b/lib/freading.h
index e0db1f7d05..1845de1a85 100644
--- 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  */