[RFA/doco] Add documentation for observer.[hc] (2nd version)

[Joel Brobecker]

Here is a second shot at the observer documentation. Hopefully, I
addressed all issues.

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

        * gdbint.texinfo (Algorithms): Add new section describing the
        Observer paradigm.
        (Top): Add menu entry to new observer appendix.
        * observer.texi: New file.
        * Makefile.in (GDBINT_DOC_SOURCE_INCLUDES): Add dependency on
        new observer.texi file.

Thanks,
-- 
Joel
-------------- next part --------------
Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.127
diff -c -3 -r1.127 gdbint.texinfo
*** gdbint.texinfo	5 Mar 2003 23:14:18 -0000	1.127
--- gdbint.texinfo	10 Mar 2003 19:54:09 -0000
***************
*** 94,99 ****
--- 94,100 ----
  * Testsuite::
  * Hints::
  
+ * GDB Observers::  @value{GDBN} Currently available observers
  * GNU Free Documentation License::  The license for this documentation
  * Index::
  @end menu
***************
*** 696,701 ****
--- 697,725 ----
  unavailable in many platforms.
  @end enumerate
  
+ @section Observing changes in @value{GDBN} internals
+ @cindex observer pattern interface
+ @cindex notifications about changes in internals
+ 
+ In order to function properly, several modules need to be notified when
+ some changes occur in the @value{GDBN} internals.  Traditionally, these
+ modules have relied on several paradigms, the most common ones being
+ hooks and gdb-events.  Unfortunately, none of these paradigms was
+ versatile enough to become the standard notification mechanism in
+ @value{GDBN}.  The fact that they only supported one ``client'' was also
+ a strong limitation.
+ 
+ A new paradigm, based on the Observer pattern of the @cite{Design
+ Patterns} book, has therefore been implemented.  The goal was to provide
+ a new interface overcoming the issues with the notification mechanisms
+ previously available.  This new interface needed to be strongly typed,
+ easy to extend, and versatile enough to be used as the standard
+ interface when adding new notifications.
+ 
+ See @ref{GDB Observers} for a brief description of the observers
+ currently implemented in GDB. The rationale for the current
+ implementation is also briefly discussed.
+ 
  @node User Interface
  
  @chapter User Interface
***************
*** 6577,6582 ****
--- 6601,6607 ----
  
  @end table
  
+ @include observer.texi
  @include fdl.texi
  
  @node Index
Index: Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.26
diff -c -3 -r1.26 Makefile.in
*** Makefile.in	3 Mar 2003 03:59:16 -0000	1.26
--- Makefile.in	10 Mar 2003 19:54:01 -0000
***************
*** 114,120 ****
  
  # Internals Manual
  GDBINT_DOC_SOURCE_INCLUDES = \
! 	$(srcdir)/fdl.texi
  GDBINT_DOC_BUILD_INCLUDES = \
  	gdb-cfg.texi \
  	GDBvn.texi
--- 114,121 ----
  
  # Internals Manual
  GDBINT_DOC_SOURCE_INCLUDES = \
! 	$(srcdir)/fdl.texi \
! 	$(srcdir)/observer.texi
  GDBINT_DOC_BUILD_INCLUDES = \
  	gdb-cfg.texi \
  	GDBvn.texi
-------------- next part --------------
A non-text attachment was scrubbed...
Name: observer.texi
Type: application/x-texinfo
Size: 2549 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/gdb-patches/attachments/20030310/ee0aa129/attachment.texi>