[PATCH] GTY documentation update

[Laurynas Biveinis]

Hi Ralf -

Thanks for your comments.

> You can make reviews even easier by ensuring that your patches are
> either inline (and not mangled) or attached but not declared as
> octet-stream MIME type, so that replying to them inline is
> straight-forward.  Thanks.

I am not sure how to achieve this with Gmail. .diff or .txt attachment
file extension perhaps? Does anyone have Gmail-specific tips here?

> Although not specified by the GNU Coding Standards or GCC's Coding
> Conventions, it is a good idea to keep the line length for ChangeLog
> entries below 80 or 72, even if only to make them look neat and un-
> wrapped in email.  ;-)

That's what I get for typing in the ChangeLog directly in e-mail. Of
course the committed version will be correctly wrapped :)

> Several lines in your patch introduce (more) trailing white space in the
> text.

Fixed.

>> +If @code{field_vec->elts} stores @code{n} elements, then @code{size}
>
> I'd use @var{n} ...

Texinfo manual says "Use the @var command to indicate metasyntactic
variables" and "Do not use @var for the names of particular variables
in programming languages." I have trouble understanding if n and size
are metasyntactic or not, so I really don't know which one to choose.

>> +At the time of @code{ggc_collect} call all pointers in the GC-marked
>
> s/of/& the/

Fixed.

>> +allocators unless all the fields are initialized manually immediatelly
>
> immediately

Fixed.

>> +after the allocation.
>
> s/the //

Fixed.

>
>> +@node Troubleshooting
>> +@section Troubleshooting the garbage collector
>> +@cindex garbage collector, troubleshooting
>> +
>> +With the current garbage collector implementation most issues should
>> +show up as GCC compilation errors.  Some of the most commonly
>> +encountered issues are described in the following.
>> +
>> +@itemize @bullet
>> +@item Gengtype does not produce allocators for a GTY-marked type.
>> +Gengtype checks if there is at least one possible path from GC roots
>> +to at least one instance of each type before outputing allocators.  If
>
> outputting

Fixed.

Here is v2 of the patch (trying attachment with .diff this time)

Further comments, OK for trunk?

2010-11-09  Laurynas Biveinis  <laurynas.biveinis@gmail.com>

        PR/46268
        * doc/gty.texi (GTY Options): Clarify that variable_size produces
        allocators taking size in bytes, compare with length option.  Add
        size calculation example.
        (Invoking the garbage collector): Ensure that sentences are
        followed by two spaces.  Describe that pointer fields must be
        initialized at ggc_collect call.
        (Troubleshooting): New section.


-- 
Laurynas
-------------- next part --------------
A non-text attachment was scrubbed...
Name: gty.texi.diff
Type: application/octet-stream
Size: 4203 bytes
Desc: not available
URL: <http://gcc.gnu.org/pipermail/gcc-patches/attachments/20101109/d8132489/attachment.obj>