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

["Ulrich Weigand" <uweigand at de dot ibm dot com>]

Eli Zaretskii wrote;

> This part is almost okay; I have a few minor comments:
> 
>  . The ChangeLog entry needs to state the name(s) of the node(s) where
>    you make the changes (in parens, as if they were names of
>    functions).

Sure, I'll do that.

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

That means the argument to set_gdbarch_sofun_address_maybe_missing
is a simple boolean.  I had thought the documentation for gdbarch
entries should refer to the entity that you pass to the set_gdbarch_
function; after all that is what the -tdep.c programmer writes.

On the other hand, the accessor function gdbarch_sofun_address_maybe_missing
does have an argument, namely the gdbarch that is being queried.  I see
that some of the other entries do show these arguments, so you could say
it should be added in the case as well.

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

I'll be happy to do it either way, please let me know which you prefer.

>  . 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.  If we're to describe the access functions, that needs
to be rephrased accordingly, of course.

Bye,
Ulrich

-- 
  Dr. Ulrich Weigand
  GNU Toolchain for Linux on System z and Cell BE
  Ulrich.Weigand@de.ibm.com