Re: [PATCH 9/9] gdb/mi: new options for -data-disassemble command

[Eli Zaretskii <eliz@gnu.org>]

> Date: Thu, 23 Jun 2022 17:05:16 +0100
> From: Andrew Burgess via Gdb-patches <gdb-patches@sourceware.org>
> Cc: Andrew Burgess <aburgess@redhat.com>
> 
> @@ -34416,31 +34418,56 @@
>  displayed; if @var{lines} is higher than the number of lines between
>  @var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr}
>  are displayed.
> +@item @var{opcodes-mode}
> +is one of @samp{none}, @samp{bytes}, or @samp{display}.  This setting
> +can only be used with @var{mode} 0.  Passing @samp{none} here will
> +prevent opcodes being included in the result; passing @samp{bytes} here
> +will include opcodes in the result, the opcodes will be formatted as for
> +@kbd{disassemble /b}; and passing @samp{display} here will include the
> +opcodes in the result, the opcodes will be formatted as for
> +@kbd{disassemble /r}.

This begs for an inner @table or @itemize, describing each of the 3
options separately.  It would be also more correct, English-wise,
since starting an @item with a lowercase letter and then writing
several sentences there is not really correct.

>  @item @var{mode}
> -is one of:
> +the use of @var{mode} is deprecated in favour of using the
> +@code{--opcodes} and @code{--source} options.  When no @var{mode} is
> +given, @var{mode} 0 will be assumed.  However, the @var{mode} is still
> +available for backward compatibility.  The @var{mode} should be one of:
>  @itemize @bullet
> -@item 0 disassembly only
> -@item 1 mixed source and disassembly (deprecated)
> -@item 2 disassembly with raw opcodes
> -@item 3 mixed source and disassembly with raw opcodes (deprecated)
> -@item 4 mixed source and disassembly
> -@item 5 mixed source and disassembly with raw opcodes
> +@item 0 disassembly only:
> +This is the default mode if no mode is specified.

This is in @itemize, so @items should appear alone on their lines, and
the text on the line below it.  But the style in which you wrote this
is better suited fore @table, so maybe just replace @itemize by @table.

> +@item 1 mixed source and disassembly (deprecated):
> +It is not possible to recreate this mode using @code{--opcodes} and
> +@code{--source} options.

Then why are we deprecating it (and the MODE argument itself)?

> -For modes 0 and 2 the @samp{asm_insns} list contains tuples with the
> -following fields:
> +For modes 0 and 2, and when the @code{--source} option is not used the
                                                                     ^^
Comma missing there.

> +When the @samp{--opcodes} option is not passed to
> +@code{-data-disassemble}, or the @samp{bytes} value is passed to
> +@samp{--opcodes}, then the bytes are formatted as a series of single
> +bytes, in hex, in ascending address order, with a single space between
> +each byte.  This format is equivalent to the @samp{/b} option being used
> +with the @kbd{disassemble} command.

A cross-reference to the description of 'disassemble' would be good
here.