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

[Eli Zaretskii <eliz@gnu.org>]

> From: Andrew Burgess <aburgess@redhat.com>
> Cc: gdb-patches@sourceware.org
> Date: Mon, 21 Feb 2022 17:27:21 +0000
> 
> I'm certainly not against renaming, if we can come up with a better
> name... maybe 'format_address_info'?  I don't know... I still kind of
> like 'format_address'...

I hope someone will come up with a better name.

> +@defun Architecture.format_address (@var{address})
> +Return a string in the format @samp{ADDRESS <SYMBOL+OFFSET>}, where
> +@samp{ADDRESS} is @var{address} formatted in hexadecimal,
> +@samp{SYMBOL} is a symbol, the address range of which, covers
> +@var{address}, and @samp{OFFSET} is the offset from @samp{SYMBOL} to
> +@var{address} in decimal.  This is the same format that @value{GDBN}
> +uses when printing address, symbol, and offset information, for
> +example, within disassembler output.
> +
> +If no @samp{SYMBOL} has an address range that covers @var{address},
> +then the @samp{<SYMBOL+OFFSET>} part is not included in the returned
> +string, instead the returned string will just contain the
> +@var{address} formatted as hexadecimal.
> +
> +In all cases, the @samp{ADDRESS} component will be padded with leading
> +zeros based on the width of an address for the current architecture.

This is okay, but needs the markup fixed.  All the places where you
use SOMETHING ("ADDRESS", "SYMBOL", etc.) should be @var{something},
i.e. have the @var markup and be in lower-case.  (To prevent confusion
with the argument @var{address}, call it something else, like
@var{addr}.)  Also, remove @samp everywhere except this single
instance:

   @samp{@var{address} <@var{symbol}+@var{offset}>}

And finally, this text:

> @samp{SYMBOL} is a symbol, the address range of which, covers
> +@var{address}

is better worded as

  @var{symbol} is the symbol to which @var{addr} belongs

Btw, is the above accurate? does GDB really guarantee that ADDR is
p[art of SYMBOL's memory? or does it just find the closest symbol
whose address is smaller than ADDR?

Thanks.