Re: [rfc/rft] [3/3] Remove stabs target macros: SOFUN_ADDRESS_MAYBE_MISSING

[Eli Zaretskii <eliz@gnu.org>]

> 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.