[RFA] Fix FrameDecorator.function help string

[RFA] Fix FrameDecorator.function help string

[Tom Tromey]

I found the FrameDecorator.function help string a bit confusing.  This
patch clears it up a bit.

I ran this through the gdb.python tests.

2016-06-20  Tom Tromey  <tom@tromey.com>

	* python/lib/gdb/FrameDecorator.py (FrameDecorator.function): Fix
	documentation.
---
 gdb/ChangeLog                        |  5 +++++
 gdb/python/lib/gdb/FrameDecorator.py | 24 ++++++++++++++++--------
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 78f427fb7e..ceb8a587fc 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,8 @@
+2016-06-20  Tom Tromey  <tom@tromey.com>
+
+	* python/lib/gdb/FrameDecorator.py (FrameDecorator.function): Fix
+	documentation.
+
 2018-03-27  Tom Tromey  <tom@tromey.com>
 
 	* utils.c (prompt_for_continue): Use unique_xmalloc_ptr.
diff --git a/gdb/python/lib/gdb/FrameDecorator.py b/gdb/python/lib/gdb/FrameDecorator.py
index 13f818ae99..607f8e7c03 100644
--- a/gdb/python/lib/gdb/FrameDecorator.py
+++ b/gdb/python/lib/gdb/FrameDecorator.py
@@ -83,14 +83,22 @@ class FrameDecorator(object):
         return None
 
     def function(self):
-        """ Return the name of the frame's function or an address of
-        the function of the frame.  First determine if this is a
-        special frame.  If not, try to determine filename from GDB's
-        frame internal function API.  Finally, if a name cannot be
-        determined return the address.  If this function returns an
-        address, GDB will attempt to determine the function name from
-        its internal minimal symbols store (for example, for inferiors
-        without debug-info)."""
+        """Return the name of the frame's function or an address of the
+        function of the frame.  A name is printed directly in a stack
+        trace.  If an address is returned, GDB will attempt to find a
+        corresponding symbol, whose name will be printed.
+
+        The default behavior of this function is:
+
+        If this instance wraps another 'FrameDecorator', the wrapped
+        object's 'function' method is called and that result is
+        returned.
+
+        Otherwise, if this instance wraps a 'gdb.Frame', then that
+        object's 'function' method is called, and that result is
+        returned.
+
+        Finally, if the frame has a PC, return the PC."""
 
         # Both gdb.Frame, and FrameDecorator have a method called
         # "function", so determine which object this is.
-- 
2.13.6

Re: [RFA] Fix FrameDecorator.function help string

[Simon Marchi]

On 2018-03-28 13:03, Tom Tromey wrote:
> I found the FrameDecorator.function help string a bit confusing.  This
> patch clears it up a bit.
> 
> I ran this through the gdb.python tests.
> 
> 2016-06-20  Tom Tromey  <tom@tromey.com>
> 
> 	* python/lib/gdb/FrameDecorator.py (FrameDecorator.function): Fix
> 	documentation.
> ---
>  gdb/ChangeLog                        |  5 +++++
>  gdb/python/lib/gdb/FrameDecorator.py | 24 ++++++++++++++++--------
>  2 files changed, 21 insertions(+), 8 deletions(-)
> 
> diff --git a/gdb/ChangeLog b/gdb/ChangeLog
> index 78f427fb7e..ceb8a587fc 100644
> --- a/gdb/ChangeLog
> +++ b/gdb/ChangeLog
> @@ -1,3 +1,8 @@
> +2016-06-20  Tom Tromey  <tom@tromey.com>
> +
> +	* python/lib/gdb/FrameDecorator.py (FrameDecorator.function): Fix
> +	documentation.
> +
>  2018-03-27  Tom Tromey  <tom@tromey.com>
> 
>  	* utils.c (prompt_for_continue): Use unique_xmalloc_ptr.
> diff --git a/gdb/python/lib/gdb/FrameDecorator.py
> b/gdb/python/lib/gdb/FrameDecorator.py
> index 13f818ae99..607f8e7c03 100644
> --- a/gdb/python/lib/gdb/FrameDecorator.py
> +++ b/gdb/python/lib/gdb/FrameDecorator.py
> @@ -83,14 +83,22 @@ class FrameDecorator(object):
>          return None
> 
>      def function(self):
> -        """ Return the name of the frame's function or an address of
> -        the function of the frame.  First determine if this is a
> -        special frame.  If not, try to determine filename from GDB's
> -        frame internal function API.  Finally, if a name cannot be
> -        determined return the address.  If this function returns an
> -        address, GDB will attempt to determine the function name from
> -        its internal minimal symbols store (for example, for inferiors
> -        without debug-info)."""
> +        """Return the name of the frame's function or an address of 
> the
> +        function of the frame.  A name is printed directly in a stack
> +        trace.  If an address is returned, GDB will attempt to find a
> +        corresponding symbol, whose name will be printed.
> +
> +        The default behavior of this function is:
> +
> +        If this instance wraps another 'FrameDecorator', the wrapped
> +        object's 'function' method is called and that result is
> +        returned.
> +
> +        Otherwise, if this instance wraps a 'gdb.Frame', then that
> +        object's 'function' method is called, and that result is
> +        returned.
> +
> +        Finally, if the frame has a PC, return the PC."""

Could you use bullets for that list?  Otherwise we don't know if these 
paragraphs are list items or just paragraphs that follow the list.

I don't know if your comment is accurate (I have never used frame 
decorators and don't know how they work), but at least I find it easier 
to read than the original.

Simon