Re: [RFA/doco] Adjust the normal_stop observer documentation

[Joel Brobecker <brobecker@gnat.com>]

[-- Attachment #1: Type: text/plain, Size: 897 bytes --]

> 2003-03-31  J. Brobecker  <brobecker@gnat.com>
> 
>         * observer.texi (GDB Observers): Adjust the documentation for the
>         normal_stop notification to better describe reality. Fix a minor
>         typo.

Second attempt, including Daniel's suggestion to document when the
breakpoint conditions and commands are evaluated relative to the
moment the normal_stop event is emitted.

The normal_stop notification has been inserted in a slightly different
location than the location I had in mind. As a consequence, the
description for this notification needed to be slightly adjusted. I took
this opportunity to fix a couple of minor nits.

New changelog:

2003-03-31  J. Brobecker  <brobecker@gnat.com>

        * observer.texi (GDB Observers): Adjust the documentation for the
        normal_stop notification to better describe reality. Fix a couple
        of minor typos.

-- 
Joel

[-- Attachment #2: observer.texi.diff --]
[-- Type: text/plain, Size: 2976 bytes --]

Index: observer.texi
===================================================================
RCS file: /cvs/src/src/gdb/doc/observer.texi,v
retrieving revision 1.1
diff -c -3 -r1.1 observer.texi
*** observer.texi	18 Mar 2003 17:44:23 -0000	1.1
--- observer.texi	1 Apr 2003 00:53:00 -0000
***************
*** 12,18 ****
  One subject can have several observers.
  
  @file{observer.c} implements an internal generic low-level event
! notification mechanism.  This generic event notification mechansim is
  then re-used to implement the exported high-level notification
  management routines for all possible notifications.
  
--- 12,18 ----
  One subject can have several observers.
  
  @file{observer.c} implements an internal generic low-level event
! notification mechanism.  This generic event notification mechanism is
  then re-used to implement the exported high-level notification
  management routines for all possible notifications.
  
***************
*** 27,33 ****
  callback is detached.  This is not a problem so far, as this contextual
  data is only used internally to hold a function pointer.  Later on, if
  a certain observer needs to provide support for user-level contextual
! data, then the generic notification mechanism will need need to be
  enhanced to allow the observer to provide a routine to deallocate the
  data when attaching the callback.
  
--- 27,33 ----
  callback is detached.  This is not a problem so far, as this contextual
  data is only used internally to hold a function pointer.  Later on, if
  a certain observer needs to provide support for user-level contextual
! data, then the generic notification mechanism will need to be
  enhanced to allow the observer to provide a routine to deallocate the
  data when attaching the callback.
  
***************
*** 39,48 ****
  @cindex @code{normal_stop} observer
  @cindex notification about inferior execution stop
  
! @value{GDBN} will notify all @code{normal_stop} observers when the
! inferior execution has just stopped, and all the associated internal
! processing (such as breakpoint commands, annotations, etc) is about to
! be performed before the @value{GDBN} prompt is returned to the user.
  
  The following interface is available to manage @code{normal_stop}
  observers:
--- 39,54 ----
  @cindex @code{normal_stop} observer
  @cindex notification about inferior execution stop
  
! @value{GDBN} notifies all @code{normal_stop} observers when the
! inferior execution has just stopped, the associated messages and
! annotations have been printed, and the control is about to be returned
! to the user. 
! 
! Note that the @code{normal_stop} notification is not emitted when
! the execution stops due to a breakpoint, and this breakpoint has
! a condition that is not met.  If the breakpoint has any associated
! commands list, the commands are executed after the notification
! is emitted.
  
  The following interface is available to manage @code{normal_stop}
  observers: