[python] [doc] PR 12930/12802 (clarify Breakpoint::stop doco)

[Phil Muldoon <pmuldoon at redhat dot com>]

This patch address the PRs 12930, and 12802 which both arise from
confusion regarding the scope of actions in the Breakpoint::stop
callback.  I have added some documentation to clarify.

Pedro, please excuse the gratuitous CC, but beyond Eli's normal review
can you please fact-check the documentation to make sure I am not
writing something about states that is incorrect.

Cheers,

Phil

--

2011-10-06  Phil Muldoon  <pmuldoon@redhat.com>

	PR python/12930
	PR python/12802

	* gdb.texinfo (Breakpoints In Python): Clarify behavior in the
	stop method.

--

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index dd0f7f6..0a66f5c 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -23552,6 +23552,18 @@ methods have a chance to execute at that location.  In this scenario
 if one of the methods returns @code{True} but the others return
 @code{False}, the inferior will still be stopped.
 
+When @value{GDBN} executes each @code{stop} method, the inferior has
+been stopped, but the internal state accounting for that inferior is
+undetermined.  As the return value from each @code{stop} method has the
+potential to instruct @value{GDBN} to restart the inferior, or keep it
+in a stopped state, this indeterminate state will remain until the
+execution scope of each @code{stop} method has been completed. Therefore
+you should not alter the execution state of the inferior (IE step, next,
+etc), alter the current frame context (IE change the current active
+frame), or alter, add or delete any breakpoint.  As a general rule, you
+should not alter any data within @value{GDBN} or the inferior at this
+time.
+
 Example @code{stop} implementation:
 
 @smallexample