Re: [patch/rfc] Separate gdbarch_data_register_pre_init

["Eli Zaretskii" <eliz@elta.co.il>]

> Date: Mon, 15 Mar 2004 12:21:07 -0500
> From: Andrew Cagney <cagney@gnu.org>
> 
> How does the doco part of this change look?

Looks okay to me, except for the following small gotchas:

> ! @var{post_init} is used to obtain an initial value for a
> ! per-architecture data-pointer @emph{after}.  Since @var{post_init} is
> ! always called after architecture creation, it both receives the fully
> ! initialized architecture and is free to call modules that use
> ! per-architecture data (care should be taken to avoid cycles in the
> ! call graph).
> ! @end deftypefun

This sounds like important notes, but they are worded too vaguely,
IMHO.  A question that popped up in my mind when I read that was: what
cycles should I avoid in the call graph, and how?

Perhaps an example would help drive these points home.

> ! current value of the per-architecture data-pointer.  If the data
> ! pointer is @code{NULL}, it is first initialize by calling the
                            ^^^^^^^^^^^^^^^^^^^^^^
A typo: it should be "initialized".

> ! The examples below assuming the following definitions:
                       ^^^^^^^^
"The examples ... assume ..."

> ! A module can extend the architecture vector, adding additional
> ! per-architecture attributes, using the @var{pre_init} method.  These
> ! attribute being set by the architecture's @var{gdbarch_init} method
> ! during architecture creation.

"These attributes are set by the architecture's @var{gdbarch_init}
method ...".

Btw, what ``attributes'' are those?  The text doesn't explain that.