[binutils-gdb] Minor comment updates in utils.h

[binutils-gdb] Minor comment updates in utils.h

[Tom Tromey]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=6b0c1154230afc0bf878993f11154dd0b3adda1a

commit 6b0c1154230afc0bf878993f11154dd0b3adda1a
Author: Tom Tromey <tom@tromey.com>
Date:   Sun Jan 2 13:59:56 2022 -0700

    Minor comment updates in utils.h
    
    This patch updates some comments in utils.h to more closely reflect
    the new reality.

Diff:
---
 gdb/utils.h | 32 +++++++++++++-------------------
 1 file changed, 13 insertions(+), 19 deletions(-)

diff --git a/gdb/utils.h b/gdb/utils.h
index 3d057466912..c1ac85497bf 100644
--- a/gdb/utils.h
+++ b/gdb/utils.h
@@ -193,11 +193,8 @@ extern struct ui_file **current_ui_gdb_stdin_ptr (void);
 extern struct ui_file **current_ui_gdb_stderr_ptr (void);
 extern struct ui_file **current_ui_gdb_stdlog_ptr (void);
 
-/* Flush STREAM.  This is a wrapper for ui_file_flush that also
-   flushes any output pending from uses of the *_filtered output
-   functions; that output is kept in a special buffer so that
-   pagination and styling are handled properly.  */
-extern void gdb_flush (struct ui_file *);
+/* Flush STREAM.  */
+extern void gdb_flush (struct ui_file *stream);
 
 /* The current top level's ui_file streams.  */
 
@@ -205,20 +202,16 @@ extern void gdb_flush (struct ui_file *);
 #define gdb_stdout (*current_ui_gdb_stdout_ptr ())
 /* Input stream */
 #define gdb_stdin (*current_ui_gdb_stdin_ptr ())
-/* Serious error notifications */
+/* Serious error notifications.  This bypasses the pager, if one is in
+   use.  */
 #define gdb_stderr (*current_ui_gdb_stderr_ptr ())
-/* Log/debug/trace messages that should bypass normal stdout/stderr
-   filtering.  For moment, always call this stream using
-   *_unfiltered.  In the very near future that restriction shall be
-   removed - either call shall be unfiltered.  (cagney 1999-06-13).  */
+/* Log/debug/trace messages that bypasses the pager, if one is in
+   use.  */
 #define gdb_stdlog (*current_ui_gdb_stdlog_ptr ())
 
 /* Truly global ui_file streams.  These are all defined in main.c.  */
 
-/* Target output that should bypass normal stdout/stderr filtering.
-   For moment, always call this stream using *_unfiltered.  In the
-   very near future that restriction shall be removed - either call
-   shall be unfiltered.  (cagney 1999-07-02).  */
+/* Target output that should bypass the pager, if one is in use.  */
 extern struct ui_file *gdb_stdtarg;
 extern struct ui_file *gdb_stdtargerr;
 extern struct ui_file *gdb_stdtargin;
@@ -227,11 +220,7 @@ extern struct ui_file *gdb_stdtargin;
 
 extern void set_screen_width_and_height (int width, int height);
 
-/* More generic printf like operations.  Filtered versions may return
-   non-locally on error.  As an extension over plain printf, these
-   support some GDB-specific format specifiers.  Particularly useful
-   here are the styling formatters: '%p[', '%p]' and '%ps'.  See
-   ui_out::message for details.  */
+/* Generic stdio-like operations.  */
 
 extern void gdb_puts (const char *, struct ui_file *);
 
@@ -243,6 +232,11 @@ extern void gdb_puts (const char *);
 
 extern void puts_tabular (char *string, int width, int right);
 
+/* Generic printf-like operations.  As an extension over plain
+   printf, these support some GDB-specific format specifiers.
+   Particularly useful here are the styling formatters: '%p[', '%p]'
+   and '%ps'.  See ui_out::message for details.  */
+
 extern void gdb_vprintf (const char *, va_list) ATTRIBUTE_PRINTF (1, 0);
 
 extern void gdb_vprintf (struct ui_file *, const char *, va_list)