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

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

[Joel Brobecker]

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

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

[-- Attachment #2: gdbint.texinfo.diff --]
[-- Type: text/plain, Size: 2645 bytes --]

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

[-- Attachment #3: observer.texi --]
[-- Type: application/x-texinfo, Size: 2609 bytes --]

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

[Eli Zaretskii]

> Date: Mon, 10 Mar 2003 11:59:59 -0800
> From: Joel Brobecker <brobecker@gnat.com>
> 
> Here is a second shot at the observer documentation. Hopefully, I
> addressed all issues.

Thanks.  I still have a few comments.

> An observer is an entity who is interested in being notified when GDB

When you introduce a new term, such as "observer" in the above text,
it is best to put it into @dfn, like this:

 An @dfn{observer} is an entity who is interested in being notified when GDB

(btw, it should be "whcih", not "who").  This makes the term stand
out, and clearly shows to the reader what is the term you introduce.


> The entity being observed is called the Subject.

Same here:

  The entity being observed is called @dfn{the Subject}.

(Btw, is it really necessary to start "Subject" with a capital S?)

Please also make sure each sentence ends with either a newline or 2
spaces after the period.

Thanks!

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

[Joel Brobecker]

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

Eli, thanks again for reviewing these doco changes.

> > An observer is an entity who is interested in being notified when GDB
> 
> When you introduce a new term, such as "observer" in the above text,
> it is best to put it into @dfn, like this:
> 
>  An @dfn{observer} is an entity who is interested in being notified when GDB

Makes sense, fixed.

> (btw, it should be "whcih", not "who").

Fixed.

> Same here:
> 
>   The entity being observed is called @dfn{the Subject}.
> 
> (Btw, is it really necessary to start "Subject" with a capital S?)

@dfn added, and capital S replaced.

I also realized that I forgot to mention that the current implementation
of the observer is not reentrant. So I added a paragraph to that
effect.

Here is the diff + ChangeLog again.

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.

-- 
Joel

[-- Attachment #2: gdbint.texinfo.diff --]
[-- Type: text/plain, Size: 2004 bytes --]

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.128
diff -c -3 -r1.128 gdbint.texinfo
*** gdbint.texinfo	10 Mar 2003 15:28:41 -0000	1.128
--- gdbint.texinfo	17 Mar 2003 06:59:37 -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
***************
*** 6597,6602 ****
--- 6621,6627 ----
  
  @end table
  
+ @include observer.texi
  @include fdl.texi
  
  @node Index

[-- Attachment #3: observer.texi --]
[-- Type: application/x-texinfo, Size: 2799 bytes --]

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

[Eli Zaretskii]

> Date: Sun, 16 Mar 2003 23:04:56 -0800
> From: Joel Brobecker <brobecker@gnat.com>
> 
> Here is the diff + ChangeLog again.

Thanks, this version is fine.

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

[Joel Brobecker]

> Thanks, this version is fine.

Thank you, the observer documentation has been checked in.

-- 
Joel