Re: RFA: Document RETURN_VALUE_ON_STACK

[Jim Blandy <jimb at zwingli dot cygnus dot com>]

> Your wording could be taken to mean that structures can't be
> passed by value in C - I would say "(note that arrays are
> passed by value in some languages, but not in C)" or something
> like that.  Other than that it looks fine to me.

You could be harsher than that.  It's a pretty lazy description.
How's this:

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/cvsfiles/devo/gdb/doc/gdbint.texinfo,v
retrieving revision 1.151
diff -c -c -b -F'^(' -r1.151 gdbint.texinfo
*** gdbint.texinfo	2000/04/16 14:54:43	1.151
--- gdbint.texinfo	2000/04/18 22:27:13
***************
*** 1875,1880 ****
--- 1875,1913 ----
  form.
  @xref{Target Architecture Definition, , Using Different Register and Memory Data Representations}.
  
+ @item RETURN_VALUE_ON_STACK(@var{type})
+ Return non-zero if values of type TYPE are returned on the stack, using
+ the ``struct convention'' (i.e., the caller provides a pointer to a
+ buffer in which the callee should store the return value).  This
+ controls how the @samp{finish} command finds a function's return value,
+ and whether an inferior function call reserves space on the stack for
+ the return value.
+ 
+ The full logic @value{GDBN} uses here is kind of odd.  
+ @itemize @bullet
+ 
+ @item
+ If the type being returned by value is not a structure, union, or array,
+ and @code{RETURN_VALUE_ON_STACK} returns zero, then @value{GDBN}
+ concludes the value is not returned using the struct convention.
+ 
+ @item
+ Otherwise, @value{GDBN} calls @code{USE_STRUCT_CONVENTION} (see below).
+ If that returns non-zero, @value{GDBN} assumes the struct convention is
+ in use.
+ 
+ @end itemize
+ 
+ In other words, to indicate that a given type is returned by value using
+ the struct convention, that type must be either a struct, union, array,
+ or something @code{RETURN_VALUE_ON_STACK} likes, @emph{and} something
+ that @code{USE_STRUCT_CONVENTION} likes.
+ 
+ Note that, in C and C++, arrays are never returned by value.  In those
+ languages, these predicates will always see a pointer type, never an
+ array type.  All the references above to arrays being returned by value
+ apply only to other languages.
+ 
  @item SOFTWARE_SINGLE_STEP_P
  Define this as 1 if the target does not have a hardware single-step
  mechanism. The macro @code{SOFTWARE_SINGLE_STEP} must also be defined.