Centralize and enhance val_print interface description comments (was: Re: [RFA v2] valprint.c / *-valprint.c: Don't lose `embedded_offset')

[Pedro Alves <pedro at codesourcery dot com>]

On Monday 07 February 2011 11:31:38, Tom Tromey wrote:

> Pedro> The comment is actually not 100% correct or clear.  It's actually
> Pedro> data of type TYPE located at VALADDR + EMBEDDED_OFFSET, which
> Pedro> came from the inferior at address ADDRESS + EMBEDDED_OFFSET.
> Pedro> ORIGINAL_VALUE, if non-NULL, is what came from ADDRESS.  (the
> Pedro> patch doesn't fix this; there are a bunch of copies of that
> Pedro> comment around, and I want to fix them all in one go in a
> Pedro> followup, or maybe in a next revision of this patch).
> 
> Or maybe nuke them all and have a single comment describing the
> "val_print protocol" somewhere.  These duplicated comments always end up
> rotting.

Indeed.  Here's a start.  Does this look clearer?

-- 
Pedro Alves

2011-02-07  Pedro Alves  <pedro@codesourcery.com>

	gdb/
	* valprint.c (val_print): Extend comment.
	* ada-valprint.c (ada_valprint): Rewrite comment deferring
	interface explanation to val_print.
	(ada_val_print_array): Adjust comment to current interface.
	(print_field_values): Adjust comment to current interface.
	* c-valprint.c (c_val_print): Rewrite comment deferring interface
	explanation to val_print.
	* f-valprint.c (f_val_print): Ditto.
	* jv-valprint.c (java_val_print): Ditto.
	* m2-valprint.c (m2_val_print): Ditto.
	* f-valprint.c (pascal_val_print): Ditto.

---
 gdb/ada-valprint.c |   25 ++++++++++---------------
 gdb/c-valprint.c   |   10 +++-------
 gdb/f-valprint.c   |    9 +++------
 gdb/jv-valprint.c  |    9 +++------
 gdb/m2-valprint.c  |    9 +++------
 gdb/p-valprint.c   |   12 +++---------
 gdb/valprint.c     |   30 +++++++++++++++++++-----------
 7 files changed, 44 insertions(+), 60 deletions(-)

Index: src/gdb/valprint.c
===================================================================
--- src.orig/gdb/valprint.c	2011-02-07 10:52:47.606705999 +0000
+++ src/gdb/valprint.c	2011-02-07 11:07:35.796706000 +0000
@@ -293,20 +293,28 @@ val_print_optimized_out (struct ui_file
   fprintf_filtered (stream, _("<optimized out>"));
 }
 
-/* Print using the given LANGUAGE the data of type TYPE located at VALADDR
-   (within GDB), which came from the inferior at address ADDRESS, onto
-   stdio stream STREAM according to OPTIONS.
+/* Print using the given LANGUAGE the data of type TYPE located at
+   VALADDR + EMBEDDED_OFFSET (within GDB), which came from the
+   inferior at address ADDRESS + EMBEDDED_OFFSET, onto stdio stream
+   STREAM according to OPTIONS.  VAL is the whole object that came
+   from ADDRESS.  VALADDR must point to the head of VAL's contents
+   buffer.
 
-   If the data are a string pointer, returns the number of string characters
-   printed.
+   The language printers will pass down an adjusted EMBEDDED_OFFSET to
+   further helper subroutines as subfields of TYPE are printed.  In
+   such cases, VALADDR is passed down unadjusted, as well as VAL, so
+   that VAL can be queried for metadata about the contents data being
+   printed, using EMBEDDED_OFFSET as an offset into VAL's contents
+   buffer.  For example: "has this field been optimized out", or "I'm
+   printing an object while inspecting a traceframe; has this
+   particular piece of data been collected?".
 
-   FIXME:  The data at VALADDR is in target byte order.  If gdb is ever
-   enhanced to be able to debug more than the single target it was compiled
-   for (specific CPU type and thus specific target byte ordering), then
-   either the print routines are going to have to take this into account,
-   or the data is going to have to be passed into here already converted
-   to the host byte ordering, whichever is more convenient.  */
+   RECURSE indicates the amount of indentation to supply before
+   continuation lines; this amount is roughly twice the value of
+   RECURSE.
 
+   If the data is printed as a string, returns the number of string
+   characters printed.  */
 
 int
 val_print (struct type *type, const gdb_byte *valaddr, int embedded_offset,
Index: src/gdb/ada-valprint.c
===================================================================
--- src.orig/gdb/ada-valprint.c	2011-02-07 10:52:47.696705998 +0000
+++ src/gdb/ada-valprint.c	2011-02-07 10:54:23.076706000 +0000
@@ -564,15 +564,9 @@ ada_printstr (struct ui_file *stream, st
 }
 
 
-/* Print data of type TYPE located at VALADDR (within GDB), which came from
-   the inferior at address ADDRESS, onto stdio stream STREAM according to
-   OPTIONS.  The data at VALADDR is in target byte order.
-
-   If the data is printed as a string, returns the number of string characters
-   printed.
-
-   RECURSE indicates the amount of indentation to supply before
-   continuation lines; this amount is roughly twice the value of RECURSE.  */
+/* See val_print for a description of the various parameters of this
+   function; they are identical.  The semantics of the return value is
+   also identical to val_print.  */
 
 int
 ada_val_print (struct type *type, const gdb_byte *valaddr,
@@ -598,7 +592,7 @@ ada_val_print (struct type *type, const
 }
 
 /* Assuming TYPE is a simple array, print the value of this array located
-   at VALADDR.  See ada_val_print for a description of the various
+   at VALADDR + OFFSET.  See ada_val_print for a description of the various
    parameters of this function; they are identical.  The semantics
    of the return value is also identical to ada_val_print.  */
 
@@ -1026,13 +1020,14 @@ print_record (struct type *type, const g
   fprintf_filtered (stream, ")");
 }
 
-/* Print out fields of value at VALADDR having structure type TYPE.
+/* Print out fields of value at VALADDR + OFFSET having structure type TYPE.
 
-   TYPE, VALADDR, STREAM, RECURSE, and OPTIONS have the
-   same meanings as in ada_print_value and ada_val_print.
+   TYPE, VALADDR, OFFSET, STREAM, RECURSE, and OPTIONS have the same
+   meanings as in ada_print_value and ada_val_print.
 
-   OUTER_TYPE and OUTER_VALADDR give type and address of enclosing record
-   (used to get discriminant values when printing variant parts).
+   OUTER_TYPE and OUTER_OFFSET give type and address of enclosing
+   record (used to get discriminant values when printing variant
+   parts).
 
    COMMA_NEEDED is 1 if fields have been printed at the current recursion
    level, so that a comma is needed before any field printed by this
Index: src/gdb/c-valprint.c
===================================================================
--- src.orig/gdb/c-valprint.c	2011-02-07 10:52:47.636706002 +0000
+++ src/gdb/c-valprint.c	2011-02-07 10:54:23.076706000 +0000
@@ -142,13 +142,9 @@ c_textual_element_type (struct type *typ
   return 0;
 }
 
-
-/* Print data of type TYPE located at VALADDR (within GDB), which came
-   from the inferior at address ADDRESS, onto stdio stream STREAM
-   according to OPTIONS.  The data at VALADDR is in target byte order.
-
-   If the data are a string pointer, returns the number of string
-   characters printed.  */
+/* See val_print for a description of the various parameters of this
+   function; they are identical.  The semantics of the return value is
+   also identical to val_print.  */
 
 int
 c_val_print (struct type *type, const gdb_byte *valaddr,
Index: src/gdb/f-valprint.c
===================================================================
--- src.orig/gdb/f-valprint.c	2011-02-07 10:52:47.656706007 +0000
+++ src/gdb/f-valprint.c	2011-02-07 10:54:23.086706001 +0000
@@ -242,12 +242,9 @@ Type node corrupt! F77 arrays cannot hav
 }
 
 
-/* Print data of type TYPE located at VALADDR (within GDB), which came from
-   the inferior at address ADDRESS, onto stdio stream STREAM according to
-   OPTIONS.  The data at VALADDR is in target byte order.
-
-   If the data are a string pointer, returns the number of string characters
-   printed.  */
+/* See val_print for a description of the various parameters of this
+   function; they are identical.  The semantics of the return value is
+   also identical to val_print.  */
 
 int
 f_val_print (struct type *type, const gdb_byte *valaddr, int embedded_offset,
Index: src/gdb/jv-valprint.c
===================================================================
--- src.orig/gdb/jv-valprint.c	2011-02-07 10:52:47.656706007 +0000
+++ src/gdb/jv-valprint.c	2011-02-07 10:54:23.086706001 +0000
@@ -474,12 +474,9 @@ java_print_value_fields (struct type *ty
   fprintf_filtered (stream, "}");
 }
 
-/* Print data of type TYPE located at VALADDR (within GDB), which came from
-   the inferior at address ADDRESS, onto stdio stream STREAM according to
-   OPTIONS.  The data at VALADDR is in target byte order.
-
-   If the data are a string pointer, returns the number of string characters
-   printed.  */
+/* See val_print for a description of the various parameters of this
+   function; they are identical.  The semantics of the return value is
+   also identical to val_print.  */
 
 int
 java_val_print (struct type *type, const gdb_byte *valaddr,
Index: src/gdb/m2-valprint.c
===================================================================
--- src.orig/gdb/m2-valprint.c	2011-02-07 10:52:47.676705996 +0000
+++ src/gdb/m2-valprint.c	2011-02-07 10:54:23.096706002 +0000
@@ -310,12 +310,9 @@ m2_print_array_contents (struct type *ty
 }
 
 
-/* Print data of type TYPE located at VALADDR (within GDB), which came from
-   the inferior at address ADDRESS, onto stdio stream STREAM according to
-   OPTIONS.  The data at VALADDR is in target byte order.
-
-   If the data are a string pointer, returns the number of string characters
-   printed.  */
+/* See val_print for a description of the various parameters of this
+   function; they are identical.  The semantics of the return value is
+   also identical to val_print.  */
 
 int
 m2_val_print (struct type *type, const gdb_byte *valaddr, int embedded_offset,
Index: src/gdb/p-valprint.c
===================================================================
--- src.orig/gdb/p-valprint.c	2011-02-07 10:52:47.586706010 +0000
+++ src/gdb/p-valprint.c	2011-02-07 10:54:23.096706002 +0000
@@ -40,15 +40,9 @@
 #include "cp-support.h"
 
 
-
-
-/* Print data of type TYPE located at VALADDR (within GDB), which came from
-   the inferior at address ADDRESS, onto stdio stream STREAM according to
-   OPTIONS.  The data at VALADDR is in target byte order.
-
-   If the data are a string pointer, returns the number of string characters
-   printed.  */
-
+/* See val_print for a description of the various parameters of this
+   function; they are identical.  The semantics of the return value is
+   also identical to val_print.  */
 
 int
 pascal_val_print (struct type *type, const gdb_byte *valaddr,