[PATCH] Document lazy computation for pretty-printer "children" method

[PATCH] Document lazy computation for pretty-printer "children" method

[Tom Tromey]

I found out recently that some users didn't know that the Python
pretty-printers "children" method should compute its result lazily.
This has been a good idea since the earliest days, but wasn't
mentioned in the docs.  This patch adds some text to this effect.

gdb/doc/ChangeLog
2019-05-10  Tom Tromey  <tromey@adacore.com>

	* python.texi (Pretty Printing API): Mention lazy computation for
	"children".
---
 gdb/doc/ChangeLog   | 5 +++++
 gdb/doc/python.texi | 6 ++++++
 2 files changed, 11 insertions(+)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index b47c38deef7..98e52bb770c 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -1371,6 +1371,12 @@ object which is convertible to a @value{GDBN} value.
 This method is optional.  If it does not exist, @value{GDBN} will act
 as though the value has no children.
 
+For efficiency, the @code{children} method should lazily compute its
+results.  This will let @value{GDBN} read as few elements as
+necessary, for example when various print settings (@pxref{Print
+Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable
+Objects}) limit the number of elements to be displayed.
+
 Children may be hidden from display based on the value of @samp{set
 print max-depth} (@pxref{Print Settings}).
 @end defun
-- 
2.20.1

Re: [PATCH] Document lazy computation for pretty-printer "children" method

[Eli Zaretskii]

> From: Tom Tromey <tromey@adacore.com>
> Cc: Tom Tromey <tromey@adacore.com>
> Date: Fri, 10 May 2019 08:33:23 -0600
> 
> I found out recently that some users didn't know that the Python
> pretty-printers "children" method should compute its result lazily.
> This has been a good idea since the earliest days, but wasn't
> mentioned in the docs.  This patch adds some text to this effect.
> 
> gdb/doc/ChangeLog
> 2019-05-10  Tom Tromey  <tromey@adacore.com>
> 
> 	* python.texi (Pretty Printing API): Mention lazy computation for
> 	"children".

Thanks, this is fine.