Re: [RFA 5/5] Explicit linespecs - documentation

[Eli Zaretskii <eliz at gnu dot org>]

> Date: Thu, 26 Jul 2012 20:49:59 -0700
> From: Keith Seitz <keiths@redhat.com>
> 
> The patch below adds documentation for explicit linespecs for both MI 
> and "Locations" chapters of the manual.

Thanks.

> Questions/comments/concerns?

Some:

> +* GDB now allows users to specify explicit locations, bypassing
> +  the linespec parser.  Feature also accessible from GDB/MI.

Without an example, this entry doesn't really say anything specific
about the new feature.

Also, "Feature also accessible from GDB/MI." is too laconic, please
make it a full sentence.

> +Linespecs may be specified implicitly or explicitly.  Implicit linespecs
> +are parsed by the linespec parser and converted into a location.
> +This often involves multiple searches through the program's symbol
> +table. For large programs, this may be extremely time-consuming.
> +Explicit linespecs avoid a lot of this searching by allowing the direct
> +specification of file name, function, and/or other source location
> +attributes.

This is too implementation oriented, and thus not really appropriate
for the user manual.  The text should:

  . explain what is an explicit spec, in a way that clarifies why it
    is called "explicit" (so that users could make a mental note of
    that, which will facilitate remembering the terminology);

  . describe the fundamental difference between the explicit and
    implicit specs, and

  . explain in user-understandable terms the advantages and
    disadvantages of each kind (explicit and implicit) of specs.

> +Explicit linespecs maybe be specified using the generalized form
> +@samp{-option value}.  The list of valid options is summarized in the
   ^^^^^^^^^^^^^^^^^^^^                     ^^^^^^^
"@samp{-@var{option} @var{value}}", and "@var{options}", since these
are not literal strings.

> +@item @var{-function}

@var is not the right markup here, since "-function" is a literal
string.  You want @code instead (here and elsewhere).

> +The value specifies the name of a function for the location.

This does not say what is the accepted form of a function.  E.g., will
"utils.c:vwarning" be accepted?

> +@item @var{-label}
> +The value specifies the name of a label for the location.

Again, please specify the precise format that is accepted by this
option.

> +                                                           This option
> +requires the use of at least one other explicit linespec option.

This is good information, but OTOH the other options do not state
which additional options, if any, they require.  Should they?

> +@item @var{-offset}
> +The value specifies an offset for the location.  This option may either be
> +an absolute (@var{-offset 3}) or relative (@var{-offset +3}) offset.

This needs to document the units in which the offset is specified, and
what is the origin of the relative offsets.  I would also suggest to
emphasize the difference between "3" and "+3".

As I wrote elsewhere, I would prefer -line to -offset, as this is more
in line with other GDB features.

> +    [ -p @var{thread-id} ] [ @var{location} | @var{explicit_location}]

I think the convention is to use '-', not '_', in these arguments.

> +An @var{explicit_location} may be used instead of a @var{location}
> +by supplying at least one of the following options:

"By supplying at least one" is not accurate, as you yourself write:

> +@item -s @var{filename}
> +The source file name of the location.  This option requires the use
> +of at least one other explicit linespec option.

Last, but not least: we should augment the doc strings of various
commands that receive linespecs with some of this information.  E.g.,
the "break" command.

Thanks.