RFA: clarify documentation for COERCE_FLOAT_TO_DOUBLE

[Jim Blandy <jimb@zwingli.cygnus.com>]

... or at least, it's meant to be a clarification.

2001-11-13  Jim Blandy  <jimb@redhat.com>

	* gdbint.texinfo (COERCE_FLOAT_TO_DOUBLE): Clarify.

Index: gdb/doc/gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.43
diff -c -r1.43 gdbint.texinfo
*** gdb/doc/gdbint.texinfo	2001/11/06 11:01:22	1.43
--- gdb/doc/gdbint.texinfo	2001/11/13 16:45:16
***************
*** 2815,2844 ****
  @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
  @findex COERCE_FLOAT_TO_DOUBLE
  @cindex promotion to @code{double}
! If we are calling a function by hand, and the function was declared
! (according to the debug info) without a prototype, should we
! automatically promote @code{float}s to @code{double}s?  This macro
! must evaluate to non-zero if we should, or zero if we should leave the
! value alone.
  
! The argument @var{actual} is the type of the value we want to pass to
! the function.  The argument @var{formal} is the type of this argument,
! as it appears in the function's definition.  Note that @var{formal} may
! be zero if we have no debugging information for the function, or if
! we're passing more arguments than are officially declared (for example,
! varargs).  This macro is never invoked if the function definitely has a
! prototype.
  
! @findex set_gdbarch_coerce_float_to_double
  @findex standard_coerce_float_to_double
! The default behavior is to promote only when we have no type information
! for the formal parameter.  This is different from the obvious behavior,
! which would be to promote whenever we have no prototype, just as the
! compiler does.  It's annoying, but some older targets rely on this.  If
! you want @value{GDBN} to follow the typical compiler behavior---to always
! promote when there is no prototype in scope---your gdbarch @code{init}
! function can call @code{set_gdbarch_coerce_float_to_double} and select
! the @code{standard_coerce_float_to_double} function.
  
  @item CPLUS_MARKER
  @findex CPLUS_MARKERz
--- 2815,2860 ----
  @item COERCE_FLOAT_TO_DOUBLE (@var{formal}, @var{actual})
  @findex COERCE_FLOAT_TO_DOUBLE
  @cindex promotion to @code{double}
! @cindex @code{float} arguments
! @cindex prototyped functions, passing arguments to
! @cindex passing arguments to prototyped functions
! Return non-zero if GDB should promote @code{float} values to
! @code{double} when calling a non-prototyped function.  The argument
! @var{actual} is the type of the value we want to pass to the function.
! The argument @var{formal} is the type of this argument, as it appears in
! the function's definition.  Note that @var{formal} may be zero if we
! have no debugging information for the function, or if we're passing more
! arguments than are officially declared (for example, varargs).  This
! macro is never invoked if the function definitely has a prototype.
  
! How you should pass arguments to a function depends on whether it was
! defined in K&R style or prototype style.  If you define a function using
! the K&R syntax that takes a @code{float} argument, then callers must
! pass that argument as a @code{double}.  If you define the function using
! the prototype syntax, then you must pass the argument as a @code{float},
! with no promotion.
  
! Unfortunately, on certain older platforms, the debug info doesn't
! indicate reliably how each function was defined.  A function type's
! @code{TYPE_FLAG_PROTOTYPED} flag may be unset, even if the function was
! defined in prototype style.  When calling a function whose
! @code{TYPE_FLAG_PROTOTYPED} flag is unset, GDB consults the
! @code{COERCE_FLOAT_TO_DOUBLE} macro to decide what to do.
! 
  @findex standard_coerce_float_to_double
! For modern targets, it is proper to assume that, if the prototype flag
! is unset, that can be trusted: @code{float} arguments should be promoted
! to @code{double}.  You should use the function
! @code{standard_coerce_float_to_double} to get this behavior.
! 
! @findex default_coerce_float_to_double
! For some older targets, if the prototype flag is unset, that doesn't
! tell us anything.  So we guess that, if we don't have a type for the
! formal parameter (@{i.e.}, the first argument to
! @code{COERCE_FLOAT_TO_DOUBLE} is null), then we should promote it;
! otherwise, we should leave it alone.  The function
! @code{default_coerce_float_to_double} provides this behavior; it is the
! default value, for compatibility with older configurations.
  
  @item CPLUS_MARKER
  @findex CPLUS_MARKERz