Docs and NEWS for breakpoint changes

Eli Zaretskii eliz@gnu.org
Wed Sep 26 21:13:00 GMT 2007


> From: Vladimir Prus <vladimir@codesourcery.com>
> Date: Wed, 26 Sep 2007 22:07:42 +0400
> Now that the code patches for my breakpoint changes are in,
> here's the doc patch and NEWS addition.

Thanks!

> Comments?

A few:

> +* Pending breakpoints where changed to not change its number when
> +  resolved.                                       ^^^

It's "breakpoints" (plural), so "its" is wrong.

"where" is also wrong; you meant "were".  But please don't use past
tense in NEWS, present tense is better:

  Pending breakpoints no longer change their number when their address
  is resolved.

> +* Support for breakpoints with multiple locations was implemented,

Avoiding passive voice makes text simpler and clearer:

   GDB now supports breakpoints with multiple locations,

(also present tense instead of past).

> +that are not enabled.  An optional @samp{(p)} suffix marks pending
> +breakpoints --- breakpoints for which address is either not yet
> +resolved, pending load of a shared library, or for which address was
> +in a shared library that was since resolved.  Such breakpoint won't
> +fire until a shared library that has the symbol or line referred by
> +breakpoint is loaded.  See below for details.

I'm left confused: if the address ``was since resolved'', then why do
we still mark the breakpoint with "(p)"?

If what matters is that the library is not yet loaded, why should we
confuse things by distinguishing the case where the address is not
resolved from the case where it is?

>                                                                  For a
> +pending breakpoint that never had its address known,

I think this is better:

  For a pending address whose address is not yet known,

> +have @samp{<MULTIPLE>} in this field -- see below for details.
                                        ^^
Please use "---" -- 3 dashes in a row, not 2 -- for an em-dash.

> +For a C++ constructor, the gcc compiler generates several function
> +bodies used in different cases.

Please use C@t{++}, it looks better in print (there are several more
instances like this one).  Also, we use "@value{NGCC}" instead of a
literal "gcc" in this manual.  And instead of "several function
bodies", isn't it more accurate to say "several instances of the
function body"?

> +For a C++ template function, a given line in the function can
> +correspond to unbounded set of instantiations.
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
"to any number of instantiations" is better.

> +For an inlined function, a given line can correspond to
> +several places where that function is inlined.

"given source line" or even "a breakpoint at a given source line" will
make things clearer, I think.

> +In all those cases, @value{GDBN} will associate the breakpoint
> +with all relevant locations.

Perhaps we better say "@value{GDBN} will insert a breakpoint at all
the relevant locations".  "Associate the breakpoint" leaves me
wondering what does "associate" mean in this context.

> +A breakpoint with multiple locations is displayed in the
> +breakpoint table using several rows --- one header row, followed
> +by one row for each breakpoint location. The header row
> +has @samp{<MULTIPLE>} in the address column.  The rows for
> +individual locations contain the actual addresses for locations,
> +and say what functions those locations are in.  The number
> +column for a location has number in the format 
> +@var{breakpoint-number}.@var{location-number}.

Example, please.  A picture is worth a thousand words.

> +Each location can be individually enabled or disabled by passing
> +the @var{breakpoint-number}.@var{location-number} to the @code{enable}
> +or @code{disable} commands.

  Each location can be individually enabled or disabled by passing
  @var{breakpoint-number}.@var{location-number} as argument to the
  @code{enable} and @code{disable} commands.

> +It's quite common to have a breakpoint inside a shared library.
> +Further, the shared library may be loaded and unloaded explicitly,

This "further" thing does not add anything to the sentence; just
remove it.

> +and possible repeatedly, as the program is executed.  To support
       ^^^^^^^^
"and possibly repeatedly".

> +any shared library is loaded or unloaded. Typically, you would
                                           ^^^
Two spaces between sentences, please.

> +a so called @dfn{pending breakpoint} --- breakpoint that is not yet
> +resolved to address.

"breakpoint whose address is not yet resolved".

> +After the program is run, whenever a new shared library is loaded,
> +@value{GDBN} reevaluates all breakpoints.  In case a newly loaded
> +shared library contains the symbol or line referred to by breakpoint,
> +breakpoint is resolved and becomes an ordinary breakpoint.  If a
> +library is unloaded, all breakpoints it in become pending again.

Suggest to reword slightly like this:

  After the program is run, whenever a new shared library is loaded,
  @value{GDBN} reevaluates all the breakpoints.  When a newly loaded
  shared library contains the symbol or line referred to by some
  pending breakpoint, that breakpoint is resolved and becomes an
  ordinary breakpoint.  When a library is unloaded, all breakpoints
  that refer to its symbols or source lines become pending again.

> +a new location will be added to the existing breakpoint.

Suggest "a new location is added to the list of locations for the
breakpoint".



More information about the Gdb-patches mailing list