[RFA] Fix FrameDecorator.function help string

Message ID 20180328170302.16233-1-tom@tromey.com
State New
Headers show
Series
  • [RFA] Fix FrameDecorator.function help string
Related show

Commit Message

Tom Tromey March 28, 2018, 5:03 p.m.
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(-)

-- 
2.13.6

Comments

Simon Marchi March 30, 2018, 4:02 p.m. | #1
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

Patch

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.