Re: [patch] Fix `return' of long/long-long results with no debuginfo

[Eli Zaretskii <eliz@gnu.org>]

> Date: Fri, 13 Mar 2009 18:11:35 +0100
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: Tom Tromey <tromey@redhat.com>, Mark Kettenis <mark.kettenis@xs4all.nl>,         drow@false.org, gdb-patches@sourceware.org
> 
> gdb/doc/
> 2009-03-13  Jan Kratochvil  <jan.kratochvil@redhat.com>
> 
> 	* gdb.texinfo (Returning): New description for missing debug info.

Thanks, this part is approved, provided that you add the missing
punctuation and clarify the text, as indicated below.

> +        The concrete registers assignment depends on the OS ABI and the
> +type being returned by the selected stack frame.

I'm not sure the reader will understand why this sentence is here.
Perhaps it is important to have this note, but then please add some
(apparently missing) text that would explain how register assignment
is relevant to the issue at hand.  Maybe you need to begin with the
normal case, where both the caller and the callee have debug info, and
take it from there to the two less obvious cases.  See below.

> +As the selected stack frame function may not have its debug info available in
> +such cases @value{GDBN} needs to find out the type to return from user.  For
             ^
Missing comma.

> +example typing @samp{return -1} with its implicit type @code{int} would set
          ^
Missing comma.  Also, please use @kbd{return -1} instead of @samp, as
you are describing keyboard input.

>                                                                    would set
> +only a part of a @code{long long int} result for a debug info less function.

I think it is better to talk about more general mismatch of an `int'
and the function's return type, because the "partial fill" case is
just a special case, and even then only on some platforms.  That's
assuming that there is indeed a place for generalization: would your
first example still work the same if the return value of the function
were `double'?

> +Therefore the implicit return type is accepted for debug info featuring
> +functions as in this case:
> +
> +@smallexample
> +Breakpoint 1, func () at gdb.base/return-nodebug.c:29
> +29        return 31;
> +(@value{GDBP}) return -1
> +Make func return now? (y or n) y
> +#0  0x004004f6 in main () at gdb.base/return-nodebug.c:43
> +43        printf ("result=%lld\n", func ());
> +(@value{GDBP})
> +@end smallexample
> +
> +But for functions missing their debug info the user is required to specify the
> +return type by an appropriate cast explicitely:
                                      ^^^^^^^^^^^
A typo.

Anyway, this is confusing: the paragraph begins by talking about
functions without debug info, but then you give an example for a
function _with_ debug info, and say "Therefore", as if the example
where GDB does accept incomplete spec of the return value somehow
_follows_ from the immediately preceeding discussion.

I would begin with describing the normal case explicitly, before the
text you wrote.  Something like:

  Normally, both the selected stack frame and the one above it have
  debug info.  @value{GDBN} uses the debug info when the value of
  @var{expression} does not have an explicit data type.  For example,
  if you type @kbd{return -1}, and the function in the current stack
  frame is declared to return a @code{long long int}, @value{GDBN}
  transparently converts the implicit @code{int} value of -1 into a
  @code{long long int}:

<Put here your first example.>

  However, if the selected stack frame does not have a debug info,
  e.g., if the function was compiled without debug info, ...

and now describe the use-case you are talking about and give your
second example.

OK?