Re: [PATCH] gdb/python: add gdb.Architecture.format_address

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 11 Feb 2022 16:17:21 +0000
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Andrew Burgess <andrew.burgess@embecosm.com>
> 
> diff --git a/gdb/NEWS b/gdb/NEWS
> index e173d38c3a1..4f4f0c2af6d 100644
> --- a/gdb/NEWS
> +++ b/gdb/NEWS
> @@ -187,6 +187,11 @@ GNU/Linux/LoongArch    loongarch*-*-linux*
>  
>  GNU/Linux/OpenRISC		or1k*-*-linux*
>  
> +  ** New function gdb.Architecture.format_address(ADDRESS), which
> +     takes an address in the currently selected inferior's address
> +     space, and returns a string representing the address.  The format
> +     of the returned string is '0x.... <symbol+offset>'.
> +
>  *** Changes in GDB 11
>  
>  * The 'set disassembler-options' command now supports specifying options
> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
> index c1a3f5f2a7e..50443f7b704 100644
> --- a/gdb/doc/python.texi
> +++ b/gdb/doc/python.texi
> @@ -6016,6 +6016,25 @@
>  @code{gdb.Architecture}.
>  @end defun
>  
> +@defun Architecture.format_address (@var{address})
> +Returns @var{address}, an address within the currently selected

Our style is to say "Return", not "Returns".

Also, saying "return ADDRESS" basically misses the main rationale of
this function, I think; see below.

> +inferior's address space, formatted as a string.  When a suitable
> +symbol can be found to associate with @var{address} this will be
> +included in the returned string, formatted like this:
> +
> +@smallexample
> +0x00001042 <symbol+16>
> +@end smallexample
> +
> +If there is no symbol that @value{GDBN} can find to associate with
> +@var{address} then the returned string will just contain
> +@var{address}.
> +
> +If @var{address} is not accessible within the current inferior's
> +address space, this function will still return a string containing
> +@var{address}.
> +@end defun

More generally, I wonder whether the name "format_address" is the best
one we could come up with.  Isn't this the equivalent of "info symbol"
CLI command?  If so, why not call it "address_to_symbol" or somesuch?

This goes back to the documentation: saying that a method takes its
argument and returns it as a string makes the reader wonder why would
we need such a trivial method.  So the documentation should start by
saying that the method returns SYMBOL+OFFSET that corresponds to
ADDRESS, and only mention that it returns ADDRESS as a string as the
fallback, when SYMBOL cannot be found.

Thanks.