[PATCH 00/14] Many small Python documentation fixes

[PATCH 00/14] Many small Python documentation fixes

[Tom Tromey]

Today I tried to fix all the documentation bugs filed against Python.
I also made a brief pass through the Python docs and did a little
minor editing.

Overall my impression is the Python docs are generally good.  They
could use a little work still -- a few more examples.  And, in some
spots the organization seems odd; for instance unwinders are discussed
before frames, which seems backward.  I didn't try to tackle any of
these bigger things today though; nor did I look outside the Python
docs.

Let me know what you think.

thanks,
Tom

[PATCH 04/14] Fix help text for "python" command

[Tom Tromey]

PR python/18380 points out that the example in the "help python" text
will only work in Python 2.  This changes the example to be valid
syntax for both Python 2 and Python 3.

gdb/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/18380:
	* python/python.c (_initialize_python): Make example in "python"
	help work in Python 3.
---
 gdb/ChangeLog       | 6 ++++++
 gdb/python/python.c | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/gdb/python/python.c b/gdb/python/python.c
index 20fc674f20a..6f798a0e461 100644
--- a/gdb/python/python.c
+++ b/gdb/python/python.c
@@ -1875,7 +1875,7 @@ Evaluate a Python command.\n\
 \n\
 The command can be given as an argument, for instance:\n\
 \n\
-    python print 23\n\
+    python print (23)\n\
 \n\
 If no argument is given, the following lines are read and used\n\
 as the Python commands.  Type a line containing \"end\" to indicate\n\
-- 
2.13.6

[PATCH 06/14] Reword gdb.GdbError text

[Tom Tromey]

PR python/23108 points out that the gdb.GdbError documentation is
somewhat difficult to find.  The exception is apparently just
mentioned in passing.  This patch introduces a new table and adds a
bit more text to try to make it more obvious.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/23108:
	* python.texi (Exception Handling): Rearrange gdb.GdbError text
	and add a table.
---
 gdb/doc/ChangeLog   |  6 ++++++
 gdb/doc/python.texi | 21 +++++++++++++++------
 2 files changed, 21 insertions(+), 6 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 8c4dd8de669..59b6b3b72db 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -528,12 +528,20 @@ message as its value and the Python call stack backtrace at the Python
 statement closest to where the @value{GDBN} error occured as the
 traceback.
 
-@findex gdb.GdbError
-When implementing @value{GDBN} commands in Python via @code{gdb.Command},
-it is useful to be able to throw an exception that doesn't cause a
-traceback to be printed.  For example, the user may have invoked the
-command incorrectly.  Use the @code{gdb.GdbError} exception
-to handle this case.  Example:
+
+When implementing @value{GDBN} commands in Python via
+@code{gdb.Command}, or functions via @code{gdb.Function}, it is useful
+to be able to throw an exception that doesn't cause a traceback to be
+printed.  For example, the user may have invoked the command
+incorrectly.  @value{GDBN} provides a special exception class that can
+be used for this purpose.
+
+@ftable @code
+@item gdb.GdbError
+When thrown from a command or function, this exception will cause the
+command or function to fail, but the Python stack will not be
+displayed.  @value{GDBN} does not throw this exception itself, but
+rather recognizes it when thrown from user Python code.  Example:
 
 @smallexample
 (gdb) python
@@ -551,6 +559,7 @@ to handle this case.  Example:
 (gdb) hello-world 42
 hello-world takes no arguments
 @end smallexample
+@end ftable
 
 @node Values From Inferior
 @subsubsection Values From Inferior
-- 
2.13.6

Re: [PATCH 06/14] Reword gdb.GdbError text

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:09 -0600
> 
> PR python/23108 points out that the gdb.GdbError documentation is
> somewhat difficult to find.  The exception is apparently just
> mentioned in passing.  This patch introduces a new table and adds a
> bit more text to try to make it more obvious.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	PR python/23108:
> 	* python.texi (Exception Handling): Rearrange gdb.GdbError text
> 	and add a table.

OK, thanks.

[PATCH 05/14] Avoid warnings from makeinfo

[Tom Tromey]

"make info" gives a number of warnings about the use of a "." in
@ref-like commands.  These come from the ".info" suffix.  I think this
suffix is redundant, and removing the suffix also removes the warning.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	* gdb.texinfo (Compilation): Use "gcc", not "gcc.info", in @xref.
	(Machine Code): Use "binutils", not "binutils.info", in @pxref.
	(Separate Debug Files): Use "ld", not "ld.info", in @ref.
	* python.texi (Objfiles In Python): Use "ld", not "ld.info", in @ref.
---
 gdb/doc/ChangeLog   | 7 +++++++
 gdb/doc/gdb.texinfo | 6 +++---
 gdb/doc/python.texi | 4 ++--
 3 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index f479feffe32..1d96c68d830 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -2019,7 +2019,7 @@ the @sc{gnu} C compiler, provides macro information if you are using
 the DWARF debugging format, and specify the option @option{-g3}.
 
 @xref{Debugging Options,,Options for Debugging Your Program or GCC,
-gcc.info, Using the @sc{gnu} Compiler Collection (GCC)}, for more
+gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more
 information on @value{NGCC} options affecting debug information.
 
 You will have the best debugging experience if you use the latest
@@ -8938,7 +8938,7 @@ This command controls the passing of target specific information to
 the disassembler.  For a list of valid options, please refer to the
 @code{-M}/@code{--disassembler-options} section of the @samp{objdump}
 manual and/or the output of @kbd{objdump --help}
-(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}).
+(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}).
 The default value is the empty string.
 
 If it is necessary to specify more than one disassembler option, then
@@ -19699,7 +19699,7 @@ also present in the corresponding debug info file.  (This is supported
 only on some operating systems, when using the ELF or PE file formats
 for binary files and the @sc{gnu} Binutils.)  For more details about
 this feature, see the description of the @option{--build-id}
-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,
 The GNU Linker}.  The debug info file's name is not specified
 explicitly by the build ID, but can be computed from the build ID, see
 below.
diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index e1b79cc30b2..8c4dd8de669 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4057,7 +4057,7 @@ is the build ID of the objfile.  Otherwise, @var{name} is a file name.
 This is supported only on some operating systems, notably those which use
 the ELF format for binary files and the @sc{gnu} Binutils.  For more details
 about this feature, see the description of the @option{--build-id}
-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,
 The GNU Linker}.
 @end defun
 
@@ -4093,7 +4093,7 @@ If the objfile does not have a build ID then the value is @code{None}.
 This is supported only on some operating systems, notably those which use
 the ELF format for binary files and the @sc{gnu} Binutils.  For more details
 about this feature, see the description of the @option{--build-id}
-command-line option in @ref{Options, , Command Line Options, ld.info,
+command-line option in @ref{Options, , Command Line Options, ld,
 The GNU Linker}.
 @end defvar
 
-- 
2.13.6

Re: [PATCH 05/14] Avoid warnings from makeinfo

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:08 -0600
> 
> "make info" gives a number of warnings about the use of a "." in
> @ref-like commands.  These come from the ".info" suffix.  I think this
> suffix is redundant, and removing the suffix also removes the warning.

Thanks, this is OK.

[PATCH 01/14] Update Python Block.end documentation

[Tom Tromey]

PR python/16033 points out that Block.end doesn't describe whether it
is inclusive or exclusive.  This patch fixes the documentation.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/16033:
	* python.texi (Blocks In Python): Document that Block.end is
	exclusive.
---
 gdb/doc/ChangeLog   | 6 ++++++
 gdb/doc/python.texi | 3 ++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 584b909c84b..86a91110e0e 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4455,7 +4455,8 @@ The start address of the block.  This attribute is not writable.
 @end defvar
 
 @defvar Block.end
-The end address of the block.  This attribute is not writable.
+One past the last address that appears in the block.  This attribute
+is not writable.
 @end defvar
 
 @defvar Block.function
-- 
2.13.6

[PATCH 11/14] Small typo fix in Basic Python node

[Tom Tromey]

I noticed that the decode_line documentation did not have parens
around the argument:

 -- Function: gdb.decode_line [expression]

This patch fixes this oversight.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	* python.texi (Basic Python): Parenthesize argument to
	decode_line.
---
 gdb/doc/ChangeLog   | 5 +++++
 gdb/doc/python.texi | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index eb4c3a53781..6eccc2b1154 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -448,7 +448,7 @@ as a string, or @code{None}.
 @end defun
 
 @findex gdb.decode_line 
-@defun gdb.decode_line @r{[}expression@r{]}
+@defun gdb.decode_line (@r{[}expression@r{]})
 Return locations of the line specified by @var{expression}, or of the
 current line if no argument was given.  This function returns a Python
 tuple containing two elements.  The first element contains a string
-- 
2.13.6

Re: [PATCH 11/14] Small typo fix in Basic Python node

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:14 -0600
> 
> I noticed that the decode_line documentation did not have parens
> around the argument:
> 
>  -- Function: gdb.decode_line [expression]
> 
> This patch fixes this oversight.

Thanks, this is obviously OK.

[PATCH 03/14] Document that Frame.block can throw

[Tom Tromey]

PR python/16484 points out that Frame.block can throw an exception,
but this is not documented.

This patch fixes the documentation.  Changing Frame.block to return
None would be nice, but I suspect it's too late for that change.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/16484:
	* python.texi (Frames In Python): Document that Frame.block can
	throw.
---
 gdb/doc/ChangeLog   | 6 ++++++
 gdb/doc/python.texi | 5 ++++-
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 86a91110e0e..e1b79cc30b2 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4321,7 +4321,10 @@ Returns the frame's resume address.
 @end defun
 
 @defun Frame.block ()
-Return the frame's code block.  @xref{Blocks In Python}.
+Return the frame's code block.  @xref{Blocks In Python}.  If the frame
+does not have a block -- for example, if there is no debugging
+information for the code in question -- then this will throw an
+exception.
 @end defun
 
 @defun Frame.function ()
-- 
2.13.6

Re: [PATCH 03/14] Document that Frame.block can throw

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:06 -0600
> 
> PR python/16484 points out that Frame.block can throw an exception,
> but this is not documented.
> 
> This patch fixes the documentation.  Changing Frame.block to return
> None would be nice, but I suspect it's too late for that change.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	PR python/16484:
> 	* python.texi (Frames In Python): Document that Frame.block can
> 	throw.

OK, thanks.

[PATCH 12/14] Mention virtual tables in Python dynamic_type documentation

[Tom Tromey]

PR python/16461 asks that the Python dynamic_type documentation
mention virtual tables; this patch implements that request.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/16461:
	* python.texi (Values From Inferior): Mention use of virtual
	table.
---
 gdb/doc/ChangeLog   |  6 ++++++
 gdb/doc/python.texi | 16 ++++++++--------
 2 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 6eccc2b1154..e310c16c0a9 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -658,14 +658,14 @@ The type of this @code{gdb.Value}.  The value of this attribute is a
 @end defvar
 
 @defvar Value.dynamic_type
-The dynamic type of this @code{gdb.Value}.  This uses C@t{++} run-time
-type information (@acronym{RTTI}) to determine the dynamic type of the
-value.  If this value is of class type, it will return the class in
-which the value is embedded, if any.  If this value is of pointer or
-reference to a class type, it will compute the dynamic type of the
-referenced object, and return a pointer or reference to that type,
-respectively.  In all other cases, it will return the value's static
-type.
+The dynamic type of this @code{gdb.Value}.  This uses the object's
+virtual table and the C@t{++} run-time type information
+(@acronym{RTTI}) to determine the dynamic type of the value.  If this
+value is of class type, it will return the class in which the value is
+embedded, if any.  If this value is of pointer or reference to a class
+type, it will compute the dynamic type of the referenced object, and
+return a pointer or reference to that type, respectively.  In all
+other cases, it will return the value's static type.
 
 Note that this feature will only work when debugging a C@t{++} program
 that includes @acronym{RTTI} for the object in question.  Otherwise,
-- 
2.13.6

Re: [PATCH 12/14] Mention virtual tables in Python dynamic_type documentation

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:15 -0600
> 
> PR python/16461 asks that the Python dynamic_type documentation
> mention virtual tables; this patch implements that request.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	PR python/16461:
> 	* python.texi (Values From Inferior): Mention use of virtual
> 	table.

OK, thanks.

[PATCH 08/14] Fix gdb.events.inferior_call documentation

[Tom Tromey]

PR python/18909 points out that the gdb.events.inferior_call
documentation was incorrect.  This patch brings it in line with the
code.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/18909:
	* python.texi (Events In Python): Fix inferior_call
	documentation.
---
 gdb/doc/ChangeLog   |  6 ++++++
 gdb/doc/python.texi | 20 ++++++++++++++------
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 2b3c8a91fd6..47691c448d2 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2987,9 +2987,16 @@ A reference to the program space (@code{gdb.Progspace}) whose objfile list has
 been cleared.  @xref{Progspaces In Python}.
 @end defvar
 
-@item events.inferior_call_pre
-Emits @code{gdb.InferiorCallPreEvent} which indicates that a function in
-the inferior is about to be called.
+@item events.inferior_call
+Emits events just before and after a function in the inferior is
+called by @value{GDBN}.  Before an inferior call, this emits an event
+of type @code{gdb.InferiorCallPreEvent}, and after an inferior call,
+this emits an event of type @code{gdb.InferiorCallPostEvent}.
+
+@table @code
+@tindex gdb.InferiorCallPreEvent
+@item @code{gdb.InferiorCallPreEvent}
+Indicates that a function in the inferior is about to be called.
 
 @defvar InferiorCallPreEvent.ptid
 The thread in which the call will be run.
@@ -2999,9 +3006,9 @@ The thread in which the call will be run.
 The location of the function to be called.
 @end defvar
 
-@item events.inferior_call_post
-Emits @code{gdb.InferiorCallPostEvent} which indicates that a function in
-the inferior has returned.
+@tindex gdb.InferiorCallPostEvent
+@item @code{gdb.InferiorCallPostEvent}
+Indicates that a function in the inferior has just been called.
 
 @defvar InferiorCallPostEvent.ptid
 The thread in which the call was run.
@@ -3010,6 +3017,7 @@ The thread in which the call was run.
 @defvar InferiorCallPostEvent.address
 The location of the function that was called.
 @end defvar
+@end table
 
 @item events.memory_changed
 Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the
-- 
2.13.6

Re: [PATCH 08/14] Fix gdb.events.inferior_call documentation

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:11 -0600
> 
> PR python/18909 points out that the gdb.events.inferior_call
> documentation was incorrect.  This patch brings it in line with the
> code.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	PR python/18909:
> 	* python.texi (Events In Python): Fix inferior_call
> 	documentation.

OK, thanks.

[PATCH 07/14] Update Python frame filter documentation

[Tom Tromey]

This fixes a few frame filter documentation omissions noted in
PR python/17752.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/17752:
	* python.texi (Frame Filter API): Remove period from subsection
	title.  Mention 100 as good default priority.
	(Frame Decorator API): Remove period from subsection title.
	Mention FrameDecorator module.
---
 gdb/doc/ChangeLog   |  8 ++++++++
 gdb/doc/python.texi | 13 ++++++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 59b6b3b72db..2b3c8a91fd6 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1625,7 +1625,7 @@ order to avoid holding information that could become stale as the
 inferior changed.
 
 @node Frame Filter API
-@subsubsection Filtering Frames.
+@subsubsection Filtering Frames
 @cindex frame filters api
 
 Frame filters are Python objects that manipulate the visibility of a
@@ -1777,11 +1777,11 @@ frame filters.  Although @code{priority} can be negative, it is
 recommended practice to assume zero is the lowest priority that a
 frame filter can be assigned.  Frame filters that have the same
 priority are executed in unsorted order in that priority slot.  This
-attribute is mandatory.
+attribute is mandatory.  100 is a good default priority.
 @end defvar
 
 @node Frame Decorator API
-@subsubsection Decorating Frames.
+@subsubsection Decorating Frames
 @cindex frame decorator api
 
 Frame decorators are sister objects to frame filters (@pxref{Frame
@@ -1805,6 +1805,13 @@ boilerplate code to decorate the content of a @code{gdb.Frame}.  It is
 recommended that other frame decorators inherit and extend this
 object, and only to override the methods needed.
 
+@tindex gdb.FrameDecorator
+@code{FrameDecorator} is defined in the Python module
+@code{gdb.FrameDecorator}, so your code can import it like:
+@smallexample
+from gdb.FrameDecorator import FrameDecorator
+@end smallexample
+
 @defun FrameDecorator.elided (self)
 
 The @code{elided} method groups frames together in a hierarchical
-- 
2.13.6

Re: [PATCH 07/14] Update Python frame filter documentation

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:10 -0600
> 
> This fixes a few frame filter documentation omissions noted in
> PR python/17752.

OK, thanks.

[PATCH 10/14] Mention Python versions in the documentation

[Tom Tromey]

This updates python.texi to note that gdb can be compiled against
either major version of Python.  It also removes the "execfile"
example, because that is specific to Python 2.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	* python.texi (Python): Mention Python versions.  Don't mention
	execfile.
---
 gdb/doc/ChangeLog   | 5 +++++
 gdb/doc/python.texi | 6 ++----
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index ccad593e247..eb4c3a53781 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -18,6 +18,8 @@
 You can extend @value{GDBN} using the @uref{http://www.python.org/,
 Python programming language}.  This feature is available only if
 @value{GDBN} was configured using @option{--with-python}.
+@value{GDBN} can be built against either Python 2 or Python 3; which
+one you have depends on this configure-time option.
 
 @cindex python directory
 Python scripts used by @value{GDBN} should be installed in
@@ -113,10 +115,6 @@ interpreter:
 The script name must end with @samp{.py} and @value{GDBN} must be configured
 to recognize the script language based on filename extension using
 the @code{script-extension} setting.  @xref{Extending GDB, ,Extending GDB}.
-
-@item python execfile ("script-name")
-This method is based on the @code{execfile} Python built-in function,
-and thus is always available.
 @end table
 
 @node Python API
-- 
2.13.6

Re: [PATCH 10/14] Mention Python versions in the documentation

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:13 -0600
> 
> This updates python.texi to note that gdb can be compiled against
> either major version of Python.  It also removes the "execfile"
> example, because that is specific to Python 2.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	* python.texi (Python): Mention Python versions.  Don't mention
> 	execfile.

OK.

[PATCH 13/14] Swap two sentences in the Pretty Printing API node

[Tom Tromey]

I thought the start of the Pretty Printing API node read a bit
strangely.  This patch swaps the first two sentences, which seems
better.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	* python.texi (Pretty Printing API): Swap sentence order.
---
 gdb/doc/ChangeLog   | 4 ++++
 gdb/doc/python.texi | 5 ++---
 2 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index e310c16c0a9..545e0c341de 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1253,10 +1253,9 @@ Python module (@pxref{gdb.types}).
 @subsubsection Pretty Printing API
 @cindex python pretty printing api
 
-An example output is provided (@pxref{Pretty Printing}).
-
 A pretty-printer is just an object that holds a value and implements a
-specific interface, defined here.
+specific interface, defined here.  An example output is provided
+(@pxref{Pretty Printing}).
 
 @defun pretty_printer.children (self)
 @value{GDBN} will call this method on a pretty-printer to compute the
-- 
2.13.6

Re: [PATCH 13/14] Swap two sentences in the Pretty Printing API node

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:16 -0600
> 
> I thought the start of the Pretty Printing API node read a bit
> strangely.  This patch swaps the first two sentences, which seems
> better.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	* python.texi (Pretty Printing API): Swap sentence order.

OK, thanks.

[PATCH 14/14] Remove periods from Python section titles

[Tom Tromey]

This removes the remaining trailing periods from the Python section
titles.  I thought these looked weird and I don't this is generally
done in the gdb documentation.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	* python.texi (Frames In Python, Blocks In Python)
	(Symbols In Python, Symbol Tables In Python)
	(Lazy Strings In Python): Remove periods from section titles.
---
 gdb/doc/ChangeLog   |  6 ++++++
 gdb/doc/python.texi | 10 +++++-----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 545e0c341de..5e2ab76d2bc 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -4223,7 +4223,7 @@ from a different place.
 @end defun
 
 @node Frames In Python
-@subsubsection Accessing inferior stack frames from Python.
+@subsubsection Accessing inferior stack frames from Python
 
 @cindex frames in python
 When the debugged program stops, @value{GDBN} is able to analyze its call
@@ -4425,7 +4425,7 @@ Stack}.
 @end defun
 
 @node Blocks In Python
-@subsubsection Accessing blocks from Python.
+@subsubsection Accessing blocks from Python
 
 @cindex blocks in python
 @tindex gdb.Block
@@ -4558,7 +4558,7 @@ writable.
 @end defvar
 
 @node Symbols In Python
-@subsubsection Python representation of Symbols.
+@subsubsection Python representation of Symbols
 
 @cindex symbols in python
 @tindex gdb.Symbol
@@ -4798,7 +4798,7 @@ The value's address is a computed location.
 @end vtable
 
 @node Symbol Tables In Python
-@subsubsection Symbol table representation in Python.
+@subsubsection Symbol table representation in Python
 
 @cindex symbol tables in python
 @tindex gdb.Symtab
@@ -5274,7 +5274,7 @@ is not writable.
 @end defvar
 
 @node Lazy Strings In Python
-@subsubsection Python representation of lazy strings.
+@subsubsection Python representation of lazy strings
 
 @cindex lazy strings in python
 @tindex gdb.LazyString
-- 
2.13.6

Re: [PATCH 14/14] Remove periods from Python section titles

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:17 -0600
> 
> This removes the remaining trailing periods from the Python section
> titles.  I thought these looked weird and I don't this is generally
> done in the gdb documentation.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	* python.texi (Frames In Python, Blocks In Python)
> 	(Symbols In Python, Symbol Tables In Python)
> 	(Lazy Strings In Python): Remove periods from section titles.

OK.

[PATCH 02/14] Fix typo in pretty-printer example

[Tom Tromey]

PR python/23487 points out that the "disable pretty-printer" example
has a typo that makes it incorrect.  This patch fixes the typo.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/23487:
	* gdb.texinfo (Pretty-Printer Commands): Fix typo in example.
---
 gdb/doc/ChangeLog   | 5 +++++
 gdb/doc/gdb.texinfo | 2 +-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 8ebbe5fecb6..f479feffe32 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -10798,7 +10798,7 @@ library2.so:
   bar
     bar1
     bar2
-(gdb) disable pretty-printer library2 bar:bar1
+(gdb) disable pretty-printer library2 bar;bar1
 1 printer disabled
 1 of 3 printers enabled
 (gdb) info pretty-printer library2
-- 
2.13.6

Re: [PATCH 02/14] Fix typo in pretty-printer example

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:05 -0600
> 
> PR python/23487 points out that the "disable pretty-printer" example
> has a typo that makes it incorrect.  This patch fixes the typo.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	PR python/23487:
> 	* gdb.texinfo (Pretty-Printer Commands): Fix typo in example.

Thanks, this is OK.

[PATCH 09/14] Update Python unwinder documentation

[Tom Tromey]

PR python/19808 points out a few issues in the Python unwinder
documentation.  This patch update the documentation for
create_unwind_info and read_register to address the issues noted, and
adds a cautionary note about writing an unwinder.

gdb/doc/ChangeLog
2018-09-08  Tom Tromey  <tom@tromey.com>

	PR python/19808:
	* python.texi (Unwinding Frames in Python): Rewrite
	create_unwind_info documentation.  Update read_register
	documentation and add a note about unwinder caution.
---
 gdb/doc/ChangeLog   |  7 +++++++
 gdb/doc/python.texi | 55 ++++++++++++++++++++++++++++++++++++++++++++---------
 2 files changed, 53 insertions(+), 9 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 47691c448d2..ccad593e247 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -2290,17 +2290,40 @@ return @code{None}.  The code in @value{GDBN} that enables writing
 unwinders in Python uses this object to return frame's ID and previous
 frame registers when @value{GDBN} core asks for them.
 
+An unwinder should do as little work as possible.  Some otherwise
+innocuous operations can cause problems (even crashes, as this code is
+not not well-hardened yet).  For example, making an inferior call from
+an unwinder is unadvisable, as an inferior call will reset
+@value{GDBN}'s stack unwinding process, potentially causing re-entrant
+unwinding.
+
 @subheading Unwinder Input
 
 An object passed to an unwinder (a @code{gdb.PendingFrame} instance)
 provides a method to read frame's registers:
 
 @defun PendingFrame.read_register (reg)
-This method returns the contents of the register @var{regn} in the
+This method returns the contents of the register @var{reg} in the
 frame as a @code{gdb.Value} object.  @var{reg} can be either a
 register number or a register name; the values are platform-specific.
 They are usually found in the corresponding
-@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.
+@file{@var{platform}-tdep.h} file in the @value{GDBN} source tree.  If
+@var{reg} does not name a register for the current architecture, this
+method will throw an exception.
+
+Note that this method will always return a @code{gdb.Value} for a
+valid register name.  This does not mean that the value will be valid.
+For example, you may request a register that an earlier unwinder could
+not unwind---the value will be unavailable.  Instead, the
+@code{gdb.Value} returned from this method will be lazy; that is, its
+underlying bits will not be fetched until it is first used.  So,
+attempting to use such a value will cause an exception at the point of
+use.
+
+The type of the returned @code{gdb.Value} depends on the register and
+the architecture.  It is common for registers to have a scalar type,
+like @code{long long}; but many other types are possible, such as
+pointer, pointer-to-function, floating point or vector types.
 @end defun
 
 It also provides a factory method to create a @code{gdb.UnwindInfo}
@@ -2313,18 +2336,32 @@ using one of functions provided by @value{GDBN}.  @var{frame_id}'s attributes
 determine which function will be used, as follows:
 
 @table @code
-@item sp, pc, special
-@code{frame_id_build_special (@var{frame_id}.sp, @var{frame_id}.pc, @var{frame_id}.special)}
-
 @item sp, pc
-@code{frame_id_build (@var{frame_id}.sp, @var{frame_id}.pc)}
+The frame is identified by the given stack address and PC.  The stack
+address must be chosen so that it is constant throughout the lifetime
+of the frame, so a typical choice is the value of the stack pointer at
+the start of the function---in the DWARF standard, this would be the
+``Call Frame Address''.
+
+This is the most common case by far.  The other cases are documented
+for completeness but are only useful in specialized situations.
 
-This is the most common case.
+@item sp, pc, special
+The frame is identified by the stack address, the PC, and a
+``special'' address.  The special address is used on architectures
+that can have frames that do not change the stack, but which are still
+distinct, for example the IA-64, which has a second stack for
+registers.  Both @var{sp} and @var{special} must be constant
+throughout the lifetime of the frame.
 
 @item sp
-@code{frame_id_build_wild (@var{frame_id}.sp)}
+The frame is identified by the stack address only.  Any other stack
+frame with a matching @var{sp} will be considered to match this frame.
+Inside gdb, this is called a ``wild frame''.  You will never need
+this.
 @end table
-The attribute values should be @code{gdb.Value}
+
+Each attribute value should be an instance of @code{gdb.Value}.
 
 @end defun
 
-- 
2.13.6

Re: [PATCH 09/14] Update Python unwinder documentation

[Eli Zaretskii]

> From: Tom Tromey <tom@tromey.com>
> Cc: Tom Tromey <tom@tromey.com>
> Date: Sat,  8 Sep 2018 14:14:12 -0600
> 
> PR python/19808 points out a few issues in the Python unwinder
> documentation.  This patch update the documentation for
> create_unwind_info and read_register to address the issues noted, and
> adds a cautionary note about writing an unwinder.
> 
> gdb/doc/ChangeLog
> 2018-09-08  Tom Tromey  <tom@tromey.com>
> 
> 	PR python/19808:
> 	* python.texi (Unwinding Frames in Python): Rewrite
> 	create_unwind_info documentation.  Update read_register
> 	documentation and add a note about unwinder caution.

OK.

Re: [PATCH 00/14] Many small Python documentation fixes

[Tom Tromey]

>>>>> "Tom" == Tom Tromey <tom@tromey.com> writes:

Tom> Today I tried to fix all the documentation bugs filed against Python.
Tom> I also made a brief pass through the Python docs and did a little
Tom> minor editing.

I'm checking this in.

Eli approved patches #1 and #4 in private email.

Tom