[users/palves/format_strings] Document the gdb-specific formatters

[Pedro Alves <palves@redhat.com>]

On 7/1/19 7:56 PM, Pedro Alves wrote:
> On 7/1/19 7:49 PM, Tom Tromey wrote:
>> Tom> I looked through all the field_fmt calls, and many of them can be
>> Tom> replaced with some other call.
>>
>> I wrote some patches to do this where it is possible.
> 
> Awesome.  I wrote a patch to implement %p[ / %p], and am now writing
> a patch to document the formatters.

Like so.  I've merged this.

From c36205f0ccc36ac47b0191c02ceb5c06459ebea3 Mon Sep 17 00:00:00 2001
From: Pedro Alves <palves@redhat.com>
Date: Mon, 1 Jul 2019 19:23:07 +0100
Subject: [PATCH] Document the gdb-specific formatters

---
 gdb/ui-out.h | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 gdb/utils.h  |  5 ++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/gdb/ui-out.h b/gdb/ui-out.h
index 67c3962654c..819038ac282 100644
--- a/gdb/ui-out.h
+++ b/gdb/ui-out.h
@@ -189,8 +189,54 @@ class ui_out
 
   void spaces (int numspaces);
   void text (const char *string);
+
+  /* Output a printf-style formatted string.  In addition to the usual
+     printf format specs, this supports a few GDB-specific
+     formatters:
+
+     - '%pF' - output a field.
+
+       The argument is a field, wrapped in any of the base_field_s
+       subclasses.  int_field for integer fields, styled_field for
+       string fields.  This is preferred over separate
+       uiout->field_int(), uiout_>field_string() etc. calls when the
+       formatted message is translatable.  E.g.:
+
+         uiout->message (_("\nWatchpoint %pF deleted because the program has "
+                         "left the block in\n"
+                         "which its expression is valid.\n"),
+                         int_field ("wpnum", b->number));
+
+     - '%p[' - output the following text in a specified style.
+       '%p]' - output the following text in the default style.
+
+       The argument to '%p[' is a ui_file_style pointer.  The argument
+       to '%p]' must be nullptr.
+
+       This is useful when you want to output some portion of a string
+       literal in some style.  E.g.:
+
+	 uiout->message (_(" %p[<repeats %u times>%p]"),
+			 metadata_style.style ().ptr (),
+			 reps, repeats, nullptr);
+
+     - '%ps' - output a styled string.
+
+       The argument is the result of a call to styled_string.  This is
+       useful when you want to output some runtime-generated string in
+       some style.  E.g.:
+
+	 uiout->message (_("this is a target address %ps.\n"),
+			 styled_string (address_style.style (),
+					paddress (gdbarch, pc)));
+
+     Note that these all "abuse" the %p printf format spec, in order
+     to be compatible with GCC's printf format checking.  This is OK
+     because code in GDB that wants to print a host address should use
+     host_address_to_string instead of %p.  */
   void message (const char *format, ...) ATTRIBUTE_PRINTF (2, 3);
   void vmessage (const char *format, va_list args) ATTRIBUTE_PRINTF (2, 0);
+
   void wrap_hint (const char *identstring);
 
   void flush ();
diff --git a/gdb/utils.h b/gdb/utils.h
index 61b7b5e3bb3..d79faf28af3 100644
--- a/gdb/utils.h
+++ b/gdb/utils.h
@@ -349,7 +349,10 @@ 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.  */
+   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.  */
 
 extern void fputs_filtered (const char *, struct ui_file *);
 
-- 
2.14.5