Documentation changes

    * ACE/ace/Dev_Poll_Reactor.h:
    * ACE/ace/MMAP_Memory_Pool.h:
    * ACE/ace/Sig_Handler.cpp:
    * ACE/ace/Sig_Handler.h:

1 files changed, 33 insertions, 45 deletions

diff --git a/ACE/ace/Sig_Handler.cpp b/ACE/ace/Sig_Handler.cpp
index 577a1e43035..029a0d6efbc 100644
--- a/ACE/ace/Sig_Handler.cpp
+++ b/ACE/ace/Sig_Handler.cpp
@@ -39,10 +39,10 @@ ace_sig_handlers_dispatch (int signum, siginfo_t *info, ucontext_t *context)
 
 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
 
-// Array of Event_Handlers that will handle the signals.
+/// Array of Event_Handlers that will handle the signals.
 ACE_Event_Handler *ACE_Sig_Handler::signal_handlers_[ACE_NSIG];
 
-// Remembers if a signal has occurred.
+/// Remembers if a signal has occurred.
 sig_atomic_t ACE_Sig_Handler::sig_pending_ = 0;
 
 
@@ -131,10 +131,9 @@ ACE_Sig_Handler::handler (int signum,
   return ACE_Sig_Handler::handler_i (signum, new_sh);
 }
 
-// Register an ACE_Event_Handler along with the corresponding SIGNUM.
-// This method does NOT acquire any locks, so it can be called from a
-// signal handler.
-
+/// Register an ACE_Event_Handler along with the corresponding SIGNUM.
+/// This method does NOT acquire any locks, so it can be called from a
+/// signal handler.
 int
 ACE_Sig_Handler::register_handler_i (int signum,
                                      ACE_Event_Handler *new_sh,
@@ -169,10 +168,9 @@ ACE_Sig_Handler::register_handler_i (int signum,
     return -1;
 }
 
-// Register an ACE_Event_Handler along with the corresponding SIGNUM.
-// This method acquires a lock, so it can't be called from a signal
-// handler, e.g., <dispatch>.
-
+/// Register an ACE_Event_Handler along with the corresponding SIGNUM.
+/// This method acquires a lock, so it can't be called from a signal
+/// handler, e.g., <dispatch>.
 int
 ACE_Sig_Handler::register_handler (int signum,
                                    ACE_Event_Handler *new_sh,
@@ -220,8 +218,7 @@ ACE_Sig_Handler::remove_handler_i (int signum,
   return new_disp->register_action (signum, old_disp);
 }
 
-// Remove an ACE_Event_Handler.
-
+/// Remove an ACE_Event_Handler.
 int
 ACE_Sig_Handler::remove_handler (int signum,
                                  ACE_Sig_Action *new_disp,
@@ -240,9 +237,8 @@ ACE_Sig_Handler::remove_handler (int signum,
   return -1;
 }
 
-// Master dispatcher function that gets called by a signal handler and
-// dispatches one handler...
-
+/// Master dispatcher function that gets called by a signal handler and
+/// dispatches one handler...
 void
 ACE_Sig_Handler::dispatch (int signum,
                            siginfo_t *siginfo,
@@ -285,13 +281,13 @@ ACE_Sig_Handler::dispatch (int signum,
 // from compiling...
 #define ACE_MAX_SIGNAL_HANDLERS ((size_t) 20)
 
-// Keeps track of the id that uniquely identifies each registered
-// signal handler.  This id can be used to cancel a timer via the
-// <remove_handler> method.
+/// Keeps track of the id that uniquely identifies each registered
+/// signal handler.  This id can be used to cancel a timer via the
+/// <remove_handler> method.
 int ACE_Sig_Handlers::sigkey_ = 0;
 
-// If this is true then a 3rd party library has registered a
-// handler...
+/// If this is true then a 3rd party library has registered a
+/// handler...
 bool ACE_Sig_Handlers::third_party_sig_handler_ = false;
 
 // Make life easier by defining typedefs...
@@ -337,9 +333,8 @@ ACE_Sig_Handlers::dump (void) const
 #endif /* ACE_HAS_DUMP */
 }
 
-// This is the method that does all the dirty work...  The basic
-// structure of this method was devised by Detlef Becker.
-
+/// This is the method that does all the dirty work...  The basic
+/// structure of this method was devised by Detlef Becker.
 int
 ACE_Sig_Handlers::register_handler (int signum,
                                     ACE_Event_Handler *new_sh,
@@ -402,10 +397,10 @@ ACE_Sig_Handlers::register_handler (int signum,
                       ACE_Sig_Adapter (new_sh,
                                        ++ACE_Sig_Handlers::sigkey_),
                       -1);
+
       // Add the ACE signal handler to the set of handlers for this
       // signal (make sure it goes before the external one if there is
       // one of these).
-
       int result = ACE_Sig_Handlers_Set::instance (signum)->insert (ace_sig_adapter);
 
       if (result == -1)
@@ -465,11 +460,10 @@ ACE_Sig_Handlers::register_handler (int signum,
   return -1;
 }
 
-// Remove the ACE_Event_Handler currently associated with <signum>.
-// Install the new disposition (if given) and return the previous
-// disposition (if desired by the caller).  Returns 0 on success and
-// -1 if <signum> is invalid.
-
+/// Remove the ACE_Event_Handler currently associated with @a signum.
+/// Install the new disposition (if given) and return the previous
+/// disposition (if desired by the caller).  Returns 0 on success and
+// -1 if @a signum is invalid.
 int
 ACE_Sig_Handlers::remove_handler (int signum,
                                   ACE_Sig_Action *new_disp,
@@ -490,7 +484,6 @@ ACE_Sig_Handlers::remove_handler (int signum,
       ACE_SIG_HANDLERS_ITERATOR handler_iterator (*handler_set);
 
       // Iterate through the set of handlers for this signal.
-
       for (ACE_Event_Handler **eh;
            handler_iterator.next (eh) != 0;
            )
@@ -501,7 +494,6 @@ ACE_Sig_Handlers::remove_handler (int signum,
           // Remove the handler if (1) its key matches the key we've
           // been told to remove or (2) if we've been told to remove
           // *all* handlers (i.e., <sigkey> == -1).
-
           if (sh->sigkey () == sigkey || sigkey == -1)
             {
               handler_set->remove (*eh);
@@ -514,7 +506,6 @@ ACE_Sig_Handlers::remove_handler (int signum,
           // If there are no more handlers left for a signal then
           // register the new disposition or restore the default
           // disposition.
-
           ACE_Sig_Action sa (SIG_DFL, (sigset_t *) 0);
 
           if (new_disp == 0)
@@ -528,9 +519,8 @@ ACE_Sig_Handlers::remove_handler (int signum,
     return -1;
 }
 
-// Master dispatcher function that gets called by a signal handler and
-// dispatches *all* the handlers...
-
+/// Master dispatcher function that gets called by a signal handler and
+/// dispatches *all* the handlers...
 void
 ACE_Sig_Handlers::dispatch (int signum,
                             siginfo_t *siginfo,
@@ -569,10 +559,9 @@ ACE_Sig_Handlers::dispatch (int signum,
       }
 }
 
-// Return the first item in the list of handlers.  Note that this will
-// trivially provide the same behavior as the ACE_Sig_Handler
-// version if there is only 1 handler registered!
-
+/// Return the first item in the list of handlers.  Note that this will
+/// trivially provide the same behavior as the ACE_Sig_Handler
+/// version if there is only 1 handler registered!
 ACE_Event_Handler *
 ACE_Sig_Handlers::handler (int signum)
 {
@@ -585,12 +574,11 @@ ACE_Sig_Handlers::handler (int signum)
   return *eh;
 }
 
-// The following is a strange bit of logic that tries to give the same
-// semantics as what happens in ACE_Sig_Handler when we replace the
-// current signal handler with a new one.  Note that if there is only
-// one signal handler the behavior will be identical.  If there is
-// more than one handler then things get weird...
-
+/// The following is a strange bit of logic that tries to give the same
+/// semantics as what happens in ACE_Sig_Handler when we replace the
+/// current signal handler with a new one.  Note that if there is only
+/// one signal handler the behavior will be identical.  If there is
+/// more than one handler then things get weird...
 ACE_Event_Handler *
 ACE_Sig_Handlers::handler (int signum, ACE_Event_Handler *new_sh)
 {