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

["Eli Zaretskii" <eliz@elta.co.il>]

> 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