[RFA] Fix FrameDecorator.function help string
Commit Message
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(-)
Comments
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
@@ -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.
@@ -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.