[Bug python/16033] New: Python API documentation misses defining some concepts

[naesten at gmail dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=16033

Bug ID: 16033
Summary: Python API documentation misses defining some concepts
Product: gdb
Version: 7.6
Status: NEW
Severity: normal
Priority: P2
Component: python
Assignee: unassigned at sourceware dot org
Reporter: naesten at gmail dot com

The meanings of some attributes/functions are not actually explained.

A few, like Block.start and Block.end, are obvious enough that this isn't
really an issue; however, many of them refer to fairly gdb-internal concepts,
like Block.global_block, Block.static_block, Block.is_global, and
Block.is_static. So, for this example, a couple of sentences defining static
and global blocks would be handy. (It also wouldn't hurt to say whether
Block.end is inclusive or exclusive, though.)

[sivachandra at google dot com]

https://sourceware.org/bugzilla/show_bug.cgi?id=16033

Siva Chandra <sivachandra at google dot com> changed:

What |Removed |Added
----------------------------------------------------------------------------
CC| |sivachandra at google dot com

--- Comment #1 from Siva Chandra <sivachandra at google dot com> ---
I am really not sure to what depth the global and static blocks should be
explained. However, at the beginning of the "Accessing blocks from Python"
section, there does exist a brief description for both of them.

[tromey at sourceware dot org]

https://sourceware.org/bugzilla/show_bug.cgi?id=16033

Tom Tromey <tromey at sourceware dot org> changed:

What |Removed |Added
----------------------------------------------------------------------------
CC| |tromey at sourceware dot org

--- Comment #2 from Tom Tromey <tromey at sourceware dot org> ---
I looked at this node in the manual and nearly all of these things
seem pretty well-documented now. There's text describing the global
and static blocks along with example source code.

block.end still doesn't say if it is inclusive though.
And, this probably needs to be updated because blocks can
be discontiguous now.

[tromey at sourceware dot org]

https://sourceware.org/bugzilla/show_bug.cgi?id=16033

Tom Tromey <tromey at sourceware dot org> changed:

What |Removed |Added
----------------------------------------------------------------------------
Assignee|unassigned at sourceware dot org |tromey at sourceware dot org

--- Comment #3 from Tom Tromey <tromey at sourceware dot org> ---
I filed PR 23617 for the non-contiguous thing.
I have a patch for the exclusive thing.

If there are other problems still in this section, let me know.

[cvs-commit at gcc dot gnu.org]

https://sourceware.org/bugzilla/show_bug.cgi?id=16033

--- Comment #4 from cvs-commit at gcc dot gnu.org <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Tom Tromey <***@sourceware.org>:

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=22eb9e92ea9b5fd1ed83cfc093d7da6d18643149

commit 22eb9e92ea9b5fd1ed83cfc093d7da6d18643149
Author: Tom Tromey <***@tromey.com>
Date: Sat Sep 8 08:59:00 2018 -0600

Update Python Block.end documentation

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-10 Tom Tromey <***@tromey.com>

PR python/16033:
* python.texi (Blocks In Python): Document that Block.end is
exclusive.

[tromey at sourceware dot org]

https://sourceware.org/bugzilla/show_bug.cgi?id=16033

Tom Tromey <tromey at sourceware dot org> changed:

What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |RESOLVED
Resolution|--- |FIXED
Target Milestone|--- |8.3

--- Comment #5 from Tom Tromey <tromey at sourceware dot org> ---
Fixed,