[rfc/rft] [3/3] Remove stabs target macros: SOFUN_ADDRESS_MAYBE_MISSING
Eli Zaretskii
eliz@gnu.org
Mon Oct 8 23:17:00 GMT 2007
> Date: Mon, 8 Oct 2007 13:19:36 +0200 (CEST)
> From: "Ulrich Weigand" <uweigand@de.ibm.com>
> Cc: gdb-patches@sourceware.org
>
> > . Please put the function prototypes where you describe them. For
> > example:
> >
> > > -@item SOFUN_ADDRESS_MAYBE_MISSING
> > > -@findex SOFUN_ADDRESS_MAYBE_MISSING
> > > +@item int gdbarch_sofun_address_maybe_missing
> > > +@findex gdbarch_sofun_address_maybe_missing
> >
> > The old SOFUN_ADDRESS_MAYBE_MISSING was a macro without arguments, but
> > the new gdbarch_sofun_address_maybe_missing is a function that accepts
> > arguments. The @item line should show the full prototype of the
> > function, including the type(s) of its argument(s).
>
> Well, the sofun_address_maybe_missing gdbarch entry is of type "v",
> i.e. it is a simple variable of type "int", not a function.
Okay, that means my example was chosen wrongly (but please do state
somewhere that this is a variable). However, IIRC you have other
changes where a macro is replaced with a function, but arguments of
that function are not shown, and that's what I'd like you to fix. A
reader of the manual should not need to consult sources to understand
how to define such a function.
> I guess the question is, what is the entity that the documentation
> should specify for gdbarch entries:
>
> - the gdbarch_... accessor function
> or
> - the argument passed to the set_gdbarch_... routine
Whatever replaced the old macro should be documented in its stead. I
thought you replaced macros with functions, but maybe I misunderstood.
> > . Some of the changes were too mechanical: replacing a macro with a
> > function sometimes needs more elaborate changes in the text to
> > avoid unclear or incorrect wording:
>
> This is because I was describing a boolean "int" value, not a
> function.
I think I saw such problems with functions as well. But if you state
clearly which ones are variables, I'll be glad to review the patch
again.
Thanks.
More information about the Gdb-patches
mailing list