[RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Joel Brobecker]

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

The following patch adds some light documentation about the new observer
paradigm introduced recently.

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

        * gdbint.texinfo: Fix a small typo.
        (Observing Changes in GDB internals): New section.
        (GDB Observers currently available): Add menu entry to new appendix.
        * observer.texi: New file.
        * Makefile.in (GDBINT_DOC_SOURCE_INCLUDES): Add dependency on
        new observer.texi file.

Cheers,
-- 
Joel

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

Index: gdbint.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdbint.texinfo,v
retrieving revision 1.127
diff -c -r1.127 gdbint.texinfo
*** gdbint.texinfo	5 Mar 2003 23:14:18 -0000	1.127
--- gdbint.texinfo	9 Mar 2003 06:45:25 -0000
***************
*** 40,46 ****
  @author Cygnus Solutions
  @page
  @tex
! \def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
  \xdef\manvers{\$Revision$}  % For use in headers, footers too
  {\parskip=0pt
  \hfill Cygnus Solutions\par
--- 40,46 ----
  @author Cygnus Solutions
  @page
  @tex
! \def\$#1${{#1}}  % Kludge: collect RCS revision info without $...$
  \xdef\manvers{\$Revision$}  % For use in headers, footers too
  {\parskip=0pt
  \hfill Cygnus Solutions\par
***************
*** 95,100 ****
--- 95,101 ----
  * Hints::
  
  * GNU Free Documentation License::  The license for this documentation
+ * GDB Observers::  @value{GDBN} Observers currently available
  * Index::
  @end menu
  
***************
*** 696,701 ****
--- 697,723 ----
  unavailable in many platforms.
  @end enumerate
  
+ @section Observing changes in @value{GDBN} internals
+ @cindex observer
+ 
+ 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.
+ 
+ The rationale for the current implementation of the Observer pattern
+ is described in @file{observer.c}.
+ 
  @node User Interface
  
  @chapter User Interface
***************
*** 6578,6583 ****
--- 6600,6606 ----
  @end table
  
  @include fdl.texi
+ @include observer.texi
  
  @node Index
  @unnumbered Index
Index: Makefile.in
===================================================================
RCS file: /cvs/src/src/gdb/doc/Makefile.in,v
retrieving revision 1.26
diff -c -r1.26 Makefile.in
*** Makefile.in	3 Mar 2003 03:59:16 -0000	1.26
--- Makefile.in	9 Mar 2003 06:45:21 -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: 315 bytes --]

Re: [RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Daniel Jacobowitz]

On Sat, Mar 08, 2003 at 10:51:55PM -0800, Joel Brobecker wrote:
> The following patch adds some light documentation about the new observer
> paradigm introduced recently.

Thanks.  Two things:


> ***************
> *** 95,100 ****
> --- 95,101 ----
>   * Hints::
>   
>   * GNU Free Documentation License::  The license for this documentation
> + * GDB Observers::  @value{GDBN} Observers currently available
>   * Index::
>   @end menu
>   

Between the GFDL and the Index is probably not a good place for the new
chapter.

> @section @code{normal_stop} Notifications
> 
> @value{GDBN} will notify all @code{normal_stop} observers when the
> inferior execution has just stopped and the @value{GDBN} prompt is
> about to be returned to the user.

Could you be a little more specific?  A lot of things can happen
between the application stopping and control returning to the user. 
For instance:
  - is it before or after breakpoint commands are run, if we hit a
breakpoint?
  - If we're single-stepping multiple times, does normal_stop get
called for each one or only for the last?

My guess is that it's closer to the prompt than to the inferior
stopping, but I haven't checked.

-- 
Daniel Jacobowitz
MontaVista Software                         Debian GNU/Linux Developer

Re: [RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Eli Zaretskii]

> Date: Sat, 8 Mar 2003 22:51:55 -0800
> From: Joel Brobecker <brobecker@gnat.com>
> 
> The following patch adds some light documentation about the new observer
> paradigm introduced recently.

Thanks.  A few minor comments below.

>         * gdbint.texinfo: Fix a small typo.
>         (Observing Changes in GDB internals): New section.
>         (GDB Observers currently available): Add menu entry to new appendix.

ChangeLog entries for the manuals should mention node names, not
section names.

>   @tex
> ! \def\$#1${{#1}}  % Kluge: collect RCS revision info without $...$
>   \xdef\manvers{\$Revision$}  % For use in headers, footers too
>   {\parskip=0pt
>   \hfill Cygnus Solutions\par
> --- 40,46 ----
>   @author Cygnus Solutions
>   @page
>   @tex
> ! \def\$#1${{#1}}  % Kludge: collect RCS revision info without $...$

I'm not sure we should make this change: there are more than a single
way to spell that word.  (It originates from German, AFAIK, where
"Kluge" is the correct spelling.)

> + * GDB Observers::  @value{GDBN} Observers currently available

I think "Currently available observers" is more English-like ;-)

> + @section Observing changes in @value{GDBN} internals
> + @cindex observer

An index entry that says just "observer" will not be helpful, I
think.  How about the following entries instead?

  @cindex observer pattern interface
  @cindex notifications about changes in internals

> + The rationale for the current implementation of the Observer pattern
> + is described in @file{observer.c}.

I'd suggest to copy that rationale from observer.c into the manual.

> @appendix @value{GDBN} Observers currently available
> 
> @section @code{normal_stop} Notifications
> 
> @value{GDBN} will notify all @code{normal_stop} observers when the
> inferior execution has just stopped and the @value{GDBN} prompt is
> about to be returned to the user.

I suggest an index entry before the last paragraph.  Something like
this:

  @cindex @code{normal_stop} observer
  @cindex notification about inferior execution stop

Re: [RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Andrew Cagney]

> ***************
>> *** 95,100 ****
>> --- 95,101 ----
>>   * Hints::
>>   
>>   * GNU Free Documentation License::  The license for this documentation
>> + * GDB Observers::  @value{GDBN} Observers currently available
>>   * Index::
>>   @end menu
>>   
> 
> 
> Between the GFDL and the Index is probably not a good place for the new
> chapter.

Just FYI, the above is an appendix (not a chapter) that contains just 
the list of observer methods and their specification.  See the recent 
discussion about moving the architecture vector doco to an appendix 
doc/gdbarch.texi for the rationale.

As for just before/after the GFDL, who knows.

Andrew

Re: [RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Joel Brobecker]

> Just FYI, the above is an appendix (not a chapter) that contains just 
> the list of observer methods and their specification.  See the recent 
> discussion about moving the architecture vector doco to an appendix 
> doc/gdbarch.texi for the rationale.

Ah, you'd like to add the specifications too? I didn't see any added
value in doing so, but now that I think more about it, it's because the
current methods do not need to pass any argument/data. But it is likely
that some of the future observers will provide some, in which case the
specifications and their associated description will be useful.  Will 
add the specs for the normal_stop observers, then.

> As for just before/after the GFDL, who knows.

I just looked at a couple of books, and the GFDL was the last appendix.
I will put change my patch to leave it last too.

-- 
Joel

Re: [RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Joel Brobecker]

Thanks, Eli and Daniel, for reviewing this patch.

I will make the recommended changes shortly, and send a followup patch.

There is one change that I am reluctant to make:
> > + The rationale for the current implementation of the Observer pattern
> > + is described in @file{observer.c}.
> 
> I'd suggest to copy that rationale from observer.c into the manual.

In my past experience, the only cases when any document describing a
piece of code remained up-to-date was when the document was embedded
with the source. So if we want this description to be in the manual, and
stay up-to-date, it needs to be automatically generated from the code.

In the long term, the plan is to automatically generate observer.texi.
How about placing a copy of the rationale in this appendix then?

-- 
Joel

Re: [RFA/doco] Add documentation for observer.[hc] (gdbint.texinfo)

[Eli Zaretskii]

> Date: Mon, 10 Mar 2003 11:01:18 -0800
> From: Joel Brobecker <brobecker@gnat.com>
> 
> How about placing a copy of the rationale in this appendix then?

Okay with me.

TIA