Re: [PATCH][BZ #6885] Clarify description of __freading and__fwriting

[Siddhesh Poyarekar <siddhesh at redhat dot com>]

Hi,

Here's v2 of the patch with Roland and Rich's suggestions
incorporated.  How does this look?

Siddhesh

ChangeLog:

	[BZ #6885]
	* manual/stdio.texi (__freading): Clarify description.
	(__fwriting): Likewise.

diff --git a/manual/stdio.texi b/manual/stdio.texi
index 7b436f0..2824497 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -364,12 +364,11 @@ They provide even finer-grained information.
 @comment stdio_ext.h
 @comment GNU
 @deftypefun int __freading (FILE *@var{stream})
-The @code{__freading} function determines whether the stream
-@var{stream} was last read from or whether it is opened read-only.  In
-this case the return value is nonzero, otherwise it is zero.
-Determining whether a stream opened for reading and writing was last
-used for writing allows to draw conclusions about the content about the
-buffer, among other things.
+The @code{__freading} function returns a nonzero value if the stream
+@var{stream} was last read from or was opened read-only.  Otherwise the
+function returns zero.  Determining whether a stream opened for reading and
+writing was last used for writing allows one to draw conclusions about the
+content of the buffer, among other things.
 
 This function is declared in @file{stdio_ext.h}.
 @end deftypefun
@@ -377,9 +376,13 @@ This function is declared in @file{stdio_ext.h}.
 @comment stdio_ext.h
 @comment GNU
 @deftypefun int __fwriting (FILE *@var{stream})
-The @code{__fwriting} function determines whether the stream
-@var{stream} was last written to or whether it is opened write-only.  In
-this case the return value is nonzero, otherwise it is zero.
+The @code{__fwriting} function returns a nonzero value if the stream
+@var{stream} was last written to or was opened write-only.  Otherwise the
+function returns zero.
+
+The @code{__freading} and @code{__fwriting} functions exist primarily for use
+by gnulib and for other legacy software.  Their use in new programs is not
+recommended.
 
 This function is declared in @file{stdio_ext.h}.
 @end deftypefun