From 6c94d966c65c67090ea04d5798eb4278332facee Mon Sep 17 00:00:00 2001
From: chatty
Date: Mon, 29 Nov 1993 12:26:28 +0000
Subject: Added documentation

---
 comm/SignalHandler.cc | 46 +++++++++++++++++++++++++++++++++++++++++++---
 comm/SignalHandler.h  |  5 ++++-
 comm/TimeOut.cc       | 24 ++++++++++++++++++++----
 3 files changed, 67 insertions(+), 8 deletions(-)

diff --git a/comm/SignalHandler.cc b/comm/SignalHandler.cc
index 1315812..3fc7fab 100644
--- a/comm/SignalHandler.cc
+++ b/comm/SignalHandler.cc
@@ -16,39 +16,79 @@
 #include "Signal.h"
 #include "Multiplexer.h"
 
+/*?class UchBaseSignalHandler
+The class \typ{UchBaseSignalHandler} is provided as a base class for safe signal handlers,
+ie. signal handlers that are activated only when no data is being transferred on a channel.
+It is a derived class of \typ{CcuBaseSignalHandler}, in which the method \fun{Handle} is
+defined to hold the signal until safe times. The virtual function \fun{DeferredHandle},
+that should be redefined in derived classes, is called later.
+The class \typ{UchBaseSignalHandler} comes with a derived class
+\typ{CcuSignalHandler} that can be used as is, without any derivation.
+?*/
+
+/*?
+Create a signal handler associated to the multiplexer \var{m},
+for the signal \var{sig}.
+?*/
 UchBaseSignalHandler :: UchBaseSignalHandler (UchBaseMultiplexer& m, int sig)
 : CcuBaseSignalHandler (sig),
   MyMpx (m)
 {
 }
 
+/*?nodoc?*/
 UchBaseSignalHandler :: ~UchBaseSignalHandler ()
 {
 }
 
-
+/*!
+Ask the multiplexer to hold the signal and call us when it is safe.
+!*/
+/*?hidden?*/
 void
 UchBaseSignalHandler :: Handle ()
 {
 	MyMpx.HandleSignal (*this);
 }
 
+/*?
+This virtual function should be redefined in derived classes. It is called
+when a signal should be handled. As the handling of the signal was
+deferred, it may happen that a signal was received more than once
+before being handled; \var{nb} holds the number of identical signals
+that were received. This function is not called during an
+interruption, and does not suffer any constraint.
+?*/
 void
-UchBaseSignalHandler :: DeferredHandle (int)
+UchBaseSignalHandler :: DeferredHandle (int nb)
 {
 }
 
+/*?class UchSignalHandler
+The class \typ{UchSignalHandler} is a derived class of \typ{UchBaseSignalHandler} that
+can be used without deriving a new class.
+Each \typ{UchSignalHandler} holds a pointer to a function which is called when a
+signal is received. This function, which is passed to the constructor, must
+take an \typ{int} argument and return \typ{void}.
+?*/
+
+/*?
+Create a signal handler for signal \var{sig}. The function \var{h} will be
+called when a signal has to be handled. Its two arguments are the identification
+of the signal, and the number of signals that were received.
+?*/
 UchSignalHandler :: UchSignalHandler (UchBaseMultiplexer& m, int sig, void (*h) (int, int))
 : UchBaseSignalHandler (m, sig),
   Handler (h)
 {
 }
 
+/*?nodoc?*/
 UchSignalHandler :: ~UchSignalHandler ()
 {
 }
 
-
+/*?hidden?*/
 void
 UchSignalHandler :: DeferredHandle (int nb)
 {
diff --git a/comm/SignalHandler.h b/comm/SignalHandler.h
index f5a7b05..fdf550f 100644
--- a/comm/SignalHandler.h
+++ b/comm/SignalHandler.h
@@ -24,11 +24,14 @@ friend	class	UchBaseMultiplexer;
 protected:
 	UchBaseMultiplexer&	MyMpx;
 	void	Handle ();
-virtual	void	DeferredHandle (int);
 
 public:
 		UchBaseSignalHandler (UchBaseMultiplexer&, int);
 virtual		~UchBaseSignalHandler ();
+
+protected:
+/*?public?*/
+virtual	void	DeferredHandle (int);
 };
 
 class UchSignalHandler : public UchBaseSignalHandler {
diff --git a/comm/TimeOut.cc b/comm/TimeOut.cc
index 72a30e2..c6cb78e 100644
--- a/comm/TimeOut.cc
+++ b/comm/TimeOut.cc
@@ -17,6 +17,22 @@
 #include "ccu/Signal.h"
 #include "Multiplexer.h"
 
+/*?class UchBaseTimeOut
+The class \typ{UchBaseTimeOut} is provided as a base class for multiplexer-based timers.
+It is a derived class of \typ{CcuCoreTimer}.
+It comes with a derived class \typ{UchTimeOut} that can be used as is.
+A timer is created with a period expressed in milliseconds. It will then
+periodically call the member function \fun{Handle}, which should be redefined
+in derived classes.
+?*/
+
+/*?
+Create a timer associated to the multiplexer \var{m},
+that will send a signal every \var{period} milliseconds, \var{pulses} times.
+If \var{pulses} is negative, the timer will send signals forever.
+Timers are activated at creation time. They are disactivated, but not destroyed, after
+their last pulse.
+?*/
 UchBaseTimeOut :: UchBaseTimeOut (UchBaseMultiplexer& m, Millisecond period, int pulses)
 : CcuCoreTimer (period, pulses, m.GetTimerSet ()),
   MyMpx (m)
@@ -27,7 +43,7 @@ UchBaseTimeOut :: UchBaseTimeOut (UchBaseMultiplexer& m, Millisecond period, int
 		Activate ();
 }
 
-/*?hidden?*/
+/*?nodoc?*/
 UchBaseTimeOut :: ~UchBaseTimeOut ()
 {
 	/* stop it */
@@ -61,7 +77,8 @@ take a \typ{Millisecond} argument and return \typ{void}.
 ?*/
 
 /*?
-Create a timer associated to the multiplexer \var{m}, that will expire every \var{period} milliseconds and call
+Create a timer associated to the multiplexer \var{m},
+that will expire every \var{period} milliseconds and call
 the function \var{handler}.
 ?*/
 UchTimeOut :: UchTimeOut (UchBaseMultiplexer& m, Millisecond period, void (*handler) (Millisecond), int pulses)
@@ -75,10 +92,9 @@ UchTimeOut :: ~UchTimeOut ()
 {
 }
 
-/*?nodoc?*/
+/*?hidden?*/
 void
 UchTimeOut :: Handle (Millisecond ref)
 {
 	(*Handler) (ref);
 }
-
-- 
cgit v1.1