[RFA] Fix FrameDecorator.function help string

[Tom Tromey <tom at tromey dot com>]

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