[PATCH] [doc] Update obsolete text about sub-blocks

[PATCH] [doc] Update obsolete text about sub-blocks

[Tom Tromey]

The manual claims that there is no way to iterate over the sub-blocks
of a gdb.Block, but this hasn't been true since commit 5166ed9c
("gdb/python: add subblocks property to gdb.Block").

This patch removes the obsolete clause and rewords the paragraph.
---
 gdb/doc/python.texi | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
index 6cafab78d58..663976f1877 100644
--- a/gdb/doc/python.texi
+++ b/gdb/doc/python.texi
@@ -6273,10 +6273,9 @@ The block nested just inside the global block is the @dfn{static
 block}.  The static block typically holds file-scoped variables and
 functions.
 
-@value{GDBN} provides a method to get a block's superblock, but there
-is currently no way to examine the sub-blocks of a block, or to
-iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
-Python}).
+There is currently no way to iterate over all the blocks in a symbol
+table (@pxref{Symbol Tables In Python}), but once a block is found,
+its super- and sub-blocks can be iterated over.
 
 Here is a short example that should help explain blocks:
 

base-commit: 2ea3f3a7ac2dd6ccd42e96d496b56aa42e7cb993
-- 
2.54.0

Re: [PATCH] [doc] Update obsolete text about sub-blocks

[Jan Vrany]

On Thu, 2026-05-14 at 13:59 -0600, Tom Tromey wrote:
> The manual claims that there is no way to iterate over the sub-blocks
> of a gdb.Block, but this hasn't been true since commit 5166ed9c
> ("gdb/python: add subblocks property to gdb.Block").

Ah, thanks! I missed that.
> 
> This patch removes the obsolete clause and rewords the paragraph.
> ---
>  gdb/doc/python.texi | 7 +++----
>  1 file changed, 3 insertions(+), 4 deletions(-)
> 
> diff --git a/gdb/doc/python.texi b/gdb/doc/python.texi
> index 6cafab78d58..663976f1877 100644
> --- a/gdb/doc/python.texi
> +++ b/gdb/doc/python.texi
> @@ -6273,10 +6273,9 @@ The block nested just inside the global block is the @dfn{static
>  block}.  The static block typically holds file-scoped variables and
>  functions.
> 
> -@value{GDBN} provides a method to get a block's superblock, but there
> -is currently no way to examine the sub-blocks of a block, or to
> -iterate over all the blocks in a symbol table (@pxref{Symbol Tables In
> -Python}).
> +There is currently no way to iterate over all the blocks in a symbol
> +table (@pxref{Symbol Tables In Python}), but once a block is found,
> +its super- and sub-blocks can be iterated over.

Reading this, I thought maybe we should drop the part talking about 
iterating all the blocks of a symtab altogether.

When I read it, my first thought was: "This is not true, one can recursively
iterate over all sub-blocks starting with global block." But then I realized
this is not true either - this iterates over all blocks in a compunit, not
in a particular symtab. 

Is it at all possible to get all blocks of given symtab (_not_ compunit)?
I can imagine some complicated way of first finding the symtab for the block
from the superblock chain and then iterating all blocks in a compunit, selecting
only those that are sub-blocks of a block whose Block.function.symtab is the 
particular symtab or something like that. 

To sum it up, I find the part about iterating all blocks in a symtab
a bit confusing.

Thanks, 

Jan

> 
>  Here is a short example that should help explain blocks:
> 
> 
> base-commit: 2ea3f3a7ac2dd6ccd42e96d496b56aa42e7cb993
> --
> 2.54.0