ChangeLogTag:Wed Nov 1 14:11:48 2000 Carlos O'Ryan <coryan@uci.edu>

1 files changed, 247 insertions, 229 deletions

diff --git a/ace/Object_Manager.h b/ace/Object_Manager.h
index 101fbaf0927..fb97befe59d 100644
--- a/ace/Object_Manager.h
+++ b/ace/Object_Manager.h
@@ -1,18 +1,17 @@
 /* -*- C++ -*- */
-// $Id$
-
-// ============================================================================
-//
-// = LIBRARY
-//    ace
-//
-// = FILENAME
-//    Object_Manager.h
-//
-// = AUTHORS
-//    David L. Levine, Matthias Kerkhoff, and Per Andersson
-//
-// ============================================================================
+
+//=============================================================================
+/**
+ *  @file    Object_Manager.h
+ *
+ *  $Id$
+ *
+ *  @author David L. Levine
+ *  @author Matthias Kerkhoff
+ *  @author and Per Andersson
+ */
+//=============================================================================
+
 
 #ifndef ACE_OBJECT_MANAGER_H
 #define ACE_OBJECT_MANAGER_H
@@ -54,199 +53,202 @@ template <class T> class ACE_Cleanup_Adapter;
 #endif /* ! ACE_APPLICATION_PREALLOCATED_ARRAY_DECLARATIONS */
 
 
+/**
+ * @class ACE_Object_Manager
+ *
+ * @brief Manager for ACE library services and singleton cleanup.
+ *
+ * The <ACE_Object_Manager> manages cleanup of objects, typically
+ * singletons, at program termination.  In addition to managing
+ * the cleanup of the ACE library, it provides an interface for
+ * application to register objects to be cleaned up.
+ * This class also shuts down ACE library services, so that they
+ * can reclaim their storage, at program termination.  It works
+ * by creating a static instance whose destructor gets called
+ * along with those of all other static objects.  Hooks are
+ * provided for application code to register objects and arrays
+ * for cleanup, e.g., destruction.  The order of such cleanup
+ * calls is in the reverse order of registration, i.e., that
+ * last object/array to register gets cleaned up first.
+ * The <ACE_Object_Manager> API includes <ACE_Managed_Object>.  That
+ * class is contained in a separate file because it is a
+ * template class, and some compilers require that template and
+ * non-template class definitions appear in separate files.
+ * Please see ace/Managed_Object.h for a description of that
+ * part of the API.  In summary, <ACE_Managed_Object> provides two
+ * adapters, the <ACE_Cleanup_Adapter> and <ACE_Managed_Object>
+ * template classes for adapting objects of any type to be
+ * easily managed by the <ACE_Object_Manager>.  There are several
+ * mechanisms for adapting objects and arrays for cleanup at
+ * program termination, in roughly increasing order of ease-of-use:
+ * 1) Derive the object's class from <ACE_Cleanup>.
+ * 2) Allow the <ACE_Object_Manager> to both dynamically allocate
+ * and deallocate the object.
+ * 3) Provide an <ACE_CLEANUP_FUNC> cleanup hook for the object or
+ * array.
+ * 4) Allow the <ACE_Object_Manager> to both preallocate the object
+ * or array, either statically in global data or dynamically on
+ * the heap, when its singleton instance is construction.
+ *
+ * There are also several mechanisms for registering objects and
+ * arrays for cleanup.  In decreasing order of flexibility and
+ * complexity (with the exception of the last mechanism):
+ *
+ * 1) ACE_Object_Manager::at_exit (void *object,
+ * ACE_CLEANUP_FUNC cleanup_hook,
+ * void *param);
+ * can be used to register any object or array for any
+ * cleanup activity at program termination.
+ * 2) ACE_Object_Manager::at_exit (ACE_Cleanup *object,
+ * void *param = 0);
+ * can be used to register an <ACE_Cleanup> object
+ * for any cleanup activity at program termination.
+ * The final mechanism is not general purpose, but can only
+ * be used to allocate objects and arrays at program startup:
+ * 3) ACE_Managed_Object::get_preallocated_object
+ * (ACE_Object_Manager::Preallocated_Object id);
+ * and
+ * ACE_Managed_Object::get_preallocated_array
+ * (ACE_Object_Manager::Preallocated_Array id);
+ * can only be used to allocate objects at program startup,
+ * either in global data or on the heap (selected at compile
+ * time).  These are intended to replace static locks, etc.
+ * Instead of creating a static <ACE_Object_Manager> instance, one
+ * can alternatively be created on the stack of the main program
+ * thread.  It is created just after entry to ::main (int, char
+ * *[]), and before any existing code in that function is
+ * executed.  To enable this alternative, add #define
+ * ACE_HAS_NONSTATIC_OBJECT_MANAGER before including the platform
+ * specific config-* file in ace/config.h prior to
+ * building the ACE library and your applications.  This #define
+ * is enabled in some config files that are supplied with ACE.
+ *
+ * To ensure a static object manager is used, #undef
+ * ACE_HAS_NONSTATIC_OBJECT_MANAGER *after* including the platform
+ * specific config-* file.
+ * Note that the ACE_Object_Manager _must_ be created before
+ * any threads are spawned by the program.
+ * If ACE_HAS_NONSTATIC_OBJECT_MANAGER is not #defined, the ACE
+ * library creates a static, singleton <ACE_Object_Manager> instance.
+ * The instance is placed in global program data, and constructed
+ * via a static object constructor.  If ACE_HAS_NONSTATIC_OBJECT_MANAGER
+ * is #defined, the <ACE_Object_Manager> instance is created on the stack
+ * of the main program thread, as noted above.
+ *
+ * With ACE_HAS_NONSTATIC_OBJECT_MANAGER enabled, the ACE
+ * library has no static objects that require destruction.
+ * However, there are two drawbacks to using it:
+ * 1) main (int, char *[]) must be declared with arguments, even
+ * if they're not used.  All of ACE is converted to this, so
+ * just applications have to be concerned with it.
+ * 2) If there any static objects that depend on those that are
+ * cleaned up by the Object_Manager, they'll get cleaned up too
+ * late.  The ACE tests do not violate this requirement.
+ * However, applications may have trouble with it.
+ * NOTE on the use of <::exit> -- <::exit> does not destroy
+ * automatic objects.  Therefore, if
+ * ACE_HAS_NONSTATIC_OBJECT_MANAGER is enabled, the
+ * <ACE_Object_Manager> instance will *not* be destroyed if
+ * <::exit> is called!  However, <ACE_OS::exit> will properly
+ * destroy the ACE_Object_Manager.  It is highly recommended
+ * that <ACE_OS::exit> be used instead of <::exit>.
+ *
+ * However, <::exit> and <ACE_OS::exit> are tricky to use
+ * properly, especially in multithread programs.  It is much
+ * safer to throw an exception (or simulate that effect) that
+ * will be caught by <main> instead of calling exit.  Then,
+ * <main> can perform any necessary application-specific cleanup
+ * and return the status value.  In addition, it's usually best
+ * to avoid calling <::exit> and <ACE_OS::exit> from threads
+ * other than the main thread.  Thanks to Jeff Greif
+ * <jmg@trivida.com> for pointing out that <::exit> doesn't
+ * destroy automatic objects, and for developing the
+ * recommendations in this paragraph.
+ *
+ * Instead of creating a static <ACE_Object_Manager>, or letting
+ * ACE create it on the stack of <main> for you, another
+ * alternative is to #define
+ * ACE_DOESNT_INSTANTIATE_NONSTATIC_OBJECT_MANAGER.  With that
+ * #define, the application must create the ACE_Object_Manager.
+ * The recommended way is to call <ACE::init> at the start of
+ * the program, and call <ACE::fini> at the end.  Alternatively,
+ * the application could explicity construct an
+ * <ACE_Object_Manager>.
+ */
 class ACE_Export ACE_Object_Manager : public ACE_Object_Manager_Base
 {
-  // = TITLE
-  //     Manager for ACE library services and singleton cleanup.
-  //
-  // = DESCRIPTION
-  //     The <ACE_Object_Manager> manages cleanup of objects, typically
-  //     singletons, at program termination.  In addition to managing
-  //     the cleanup of the ACE library, it provides an interface for
-  //     application to register objects to be cleaned up.
-  //
-  //     This class also shuts down ACE library services, so that they
-  //     can reclaim their storage, at program termination.  It works
-  //     by creating a static instance whose destructor gets called
-  //     along with those of all other static objects.  Hooks are
-  //     provided for application code to register objects and arrays
-  //     for cleanup, e.g., destruction.  The order of such cleanup
-  //     calls is in the reverse order of registration, i.e., that
-  //     last object/array to register gets cleaned up first.
-  //
-  //     The <ACE_Object_Manager> API includes <ACE_Managed_Object>.  That
-  //     class is contained in a separate file because it is a
-  //     template class, and some compilers require that template and
-  //     non-template class definitions appear in separate files.
-  //     Please see ace/Managed_Object.h for a description of that
-  //     part of the API.  In summary, <ACE_Managed_Object> provides two
-  //     adapters, the <ACE_Cleanup_Adapter> and <ACE_Managed_Object>
-  //     template classes for adapting objects of any type to be
-  //     easily managed by the <ACE_Object_Manager>.  There are several
-  //     mechanisms for adapting objects and arrays for cleanup at
-  //     program termination, in roughly increasing order of ease-of-use:
-  //
-  //     1) Derive the object's class from <ACE_Cleanup>.
-  //     2) Allow the <ACE_Object_Manager> to both dynamically allocate
-  //        and deallocate the object.
-  //     3) Provide an <ACE_CLEANUP_FUNC> cleanup hook for the object or
-  //        array.
-  //     4) Allow the <ACE_Object_Manager> to both preallocate the object
-  //        or array, either statically in global data or dynamically on
-  //        the heap, when its singleton instance is construction.
-  //
-  //     There are also several mechanisms for registering objects and
-  //     arrays for cleanup.  In decreasing order of flexibility and
-  //     complexity (with the exception of the last mechanism):
-  //
-  //      1) ACE_Object_Manager::at_exit (void *object,
-  //                                      ACE_CLEANUP_FUNC cleanup_hook,
-  //                                      void *param);
-  //         can be used to register any object or array for any
-  //         cleanup activity at program termination.
-  //
-  //      2) ACE_Object_Manager::at_exit (ACE_Cleanup *object,
-  //                                      void *param = 0);
-  //         can be used to register an <ACE_Cleanup> object
-  //         for any cleanup activity at program termination.
-  //
-  //      The final mechanism is not general purpose, but can only
-  //      be used to allocate objects and arrays at program startup:
-  //
-  //      3) ACE_Managed_Object::get_preallocated_object
-  //           (ACE_Object_Manager::Preallocated_Object id);
-  //         and
-  //         ACE_Managed_Object::get_preallocated_array
-  //           (ACE_Object_Manager::Preallocated_Array id);
-  //         can only be used to allocate objects at program startup,
-  //         either in global data or on the heap (selected at compile
-  //         time).  These are intended to replace static locks, etc.
-  //
-  //     Instead of creating a static <ACE_Object_Manager> instance, one
-  //     can alternatively be created on the stack of the main program
-  //     thread.  It is created just after entry to ::main (int, char
-  //     *[]), and before any existing code in that function is
-  //     executed.  To enable this alternative, add #define
-  //     ACE_HAS_NONSTATIC_OBJECT_MANAGER before including the platform
-  //     specific config-* file in ace/config.h prior to
-  //     building the ACE library and your applications.  This #define
-  //     is enabled in some config files that are supplied with ACE.
-  //     To ensure a static object manager is used, #undef
-  //     ACE_HAS_NONSTATIC_OBJECT_MANAGER *after* including the platform
-  //     specific config-* file.
-  //
-  //     Note that the ACE_Object_Manager _must_ be created before
-  //     any threads are spawned by the program.
-  //
-  //     If ACE_HAS_NONSTATIC_OBJECT_MANAGER is not #defined, the ACE
-  //     library creates a static, singleton <ACE_Object_Manager> instance.
-  //     The instance is placed in global program data, and constructed
-  //     via a static object constructor.  If ACE_HAS_NONSTATIC_OBJECT_MANAGER
-  //     is #defined, the <ACE_Object_Manager> instance is created on the stack
-  //     of the main program thread, as noted above.
-  //
-  //     With ACE_HAS_NONSTATIC_OBJECT_MANAGER enabled, the ACE
-  //     library has no static objects that require destruction.
-  //     However, there are two drawbacks to using it:
-  //
-  //     1) main (int, char *[]) must be declared with arguments, even
-  //        if they're not used.  All of ACE is converted to this, so
-  //        just applications have to be concerned with it.
-  //
-  //     2) If there any static objects that depend on those that are
-  //        cleaned up by the Object_Manager, they'll get cleaned up too
-  //        late.  The ACE tests do not violate this requirement.
-  //        However, applications may have trouble with it.
-  //
-  //     NOTE on the use of <::exit> -- <::exit> does not destroy
-  //     automatic objects.  Therefore, if
-  //     ACE_HAS_NONSTATIC_OBJECT_MANAGER is enabled, the
-  //     <ACE_Object_Manager> instance will *not* be destroyed if
-  //     <::exit> is called!  However, <ACE_OS::exit> will properly
-  //     destroy the ACE_Object_Manager.  It is highly recommended
-  //     that <ACE_OS::exit> be used instead of <::exit>.
-  //
-  //     However, <::exit> and <ACE_OS::exit> are tricky to use
-  //     properly, especially in multithread programs.  It is much
-  //     safer to throw an exception (or simulate that effect) that
-  //     will be caught by <main> instead of calling exit.  Then,
-  //     <main> can perform any necessary application-specific cleanup
-  //     and return the status value.  In addition, it's usually best
-  //     to avoid calling <::exit> and <ACE_OS::exit> from threads
-  //     other than the main thread.  Thanks to Jeff Greif
-  //     <jmg@trivida.com> for pointing out that <::exit> doesn't
-  //     destroy automatic objects, and for developing the
-  //     recommendations in this paragraph.
-  //
-  //     Instead of creating a static <ACE_Object_Manager>, or letting
-  //     ACE create it on the stack of <main> for you, another
-  //     alternative is to #define
-  //     ACE_DOESNT_INSTANTIATE_NONSTATIC_OBJECT_MANAGER.  With that
-  //     #define, the application must create the ACE_Object_Manager.
-  //     The recommended way is to call <ACE::init> at the start of
-  //     the program, and call <ACE::fini> at the end.  Alternatively,
-  //     the application could explicity construct an
-  //     <ACE_Object_Manager>.
 
 public:
+  /**
+   * Explicitly initialize (construct the singleton instance of) the
+   * ACE_Object_Manager.  Returns 0 on success, -1 on failure, and 1
+   * if it had already been called.
+   */
   virtual int init (void);
-  // Explicitly initialize (construct the singleton instance of) the
-  // ACE_Object_Manager.  Returns 0 on success, -1 on failure, and 1
-  // if it had already been called.
 
+  /**
+   * Explicitly destroy the singleton instance of the
+   * ACE_Object_Manager.  Returns 0 on success, -1 on failure, and 1
+   * if it had already been called.
+   */
   virtual int fini (void);
-  // Explicitly destroy the singleton instance of the
-  // ACE_Object_Manager.  Returns 0 on success, -1 on failure, and 1
-  // if it had already been called.
 
+  /**
+   * Returns 1 before the ACE_Object_Manager has been constructed.
+   * This flag can be used to determine if the program is constructing
+   * static objects.  If no static object spawns any threads, the
+   * program will be single-threaded when this flag returns 1.  (Note
+   * that the program still might construct some static objects when
+   * this flag returns 0, if ACE_HAS_NONSTATIC_OBJECT_MANAGER is not
+   * defined.)
+   */
   static int starting_up (void);
-  // Returns 1 before the ACE_Object_Manager has been constructed.
-  // This flag can be used to determine if the program is constructing
-  // static objects.  If no static object spawns any threads, the
-  // program will be single-threaded when this flag returns 1.  (Note
-  // that the program still might construct some static objects when
-  // this flag returns 0, if ACE_HAS_NONSTATIC_OBJECT_MANAGER is not
-  // defined.)
 
+  /**
+   * Returns 1 after the ACE_Object_Manager has been destroyed.  This
+   * flag can be used to determine if the program is in the midst of
+   * destroying static objects.  (Note that the program might destroy
+   * some static objects before this flag can return 1, if
+   * ACE_HAS_NONSTATIC_OBJECT_MANAGER is not defined.)
+   */
   static int shutting_down (void);
-  // Returns 1 after the ACE_Object_Manager has been destroyed.  This
-  // flag can be used to determine if the program is in the midst of
-  // destroying static objects.  (Note that the program might destroy
-  // some static objects before this flag can return 1, if
-  // ACE_HAS_NONSTATIC_OBJECT_MANAGER is not defined.)
 
+  /**
+   * Register an ACE_Cleanup object for cleanup at process
+   * termination.  The object is deleted via the
+   * <ace_cleanup_destroyer>.  If you need more flexiblity, see the
+   * <other at_exit> method below.  For OS's that do not have
+   * processes, cleanup takes place at the end of <main>.  Returns 0
+   * on success.  On failure, returns -1 and sets errno to: EAGAIN if
+   * shutting down, ENOMEM if insufficient virtual memory, or EEXIST
+   * if the object (or array) had already been registered.
+   */
   static int at_exit (ACE_Cleanup *object, void *param = 0);
-  // Register an ACE_Cleanup object for cleanup at process
-  // termination.  The object is deleted via the
-  // <ace_cleanup_destroyer>.  If you need more flexiblity, see the
-  // <other at_exit> method below.  For OS's that do not have
-  // processes, cleanup takes place at the end of <main>.  Returns 0
-  // on success.  On failure, returns -1 and sets errno to: EAGAIN if
-  // shutting down, ENOMEM if insufficient virtual memory, or EEXIST
-  // if the object (or array) had already been registered.
 
+  /**
+   * Register an object (or array) for cleanup at process termination.
+   * "cleanup_hook" points to a (global, or static member) function
+   * that is called for the object or array when it to be destroyed.
+   * It may perform any necessary cleanup specific for that object or
+   * its class.  "param" is passed as the second parameter to the
+   * "cleanup_hook" function; the first parameter is the object (or
+   * array) to be destroyed.  "cleanup_hook", for example, may delete
+   * the object (or array).  For OS's that do not have processes, this
+   * function is the same as <at_thread_exit>.  Returns 0 on success.
+   * On failure, returns -1 and sets errno to: EAGAIN if shutting
+   * down, ENOMEM if insufficient virtual memory, or EEXIST if the
+   * object (or array) had already been registered.
+   */
   static int at_exit (void *object,
                       ACE_CLEANUP_FUNC cleanup_hook,
                       void *param);
-  // Register an object (or array) for cleanup at process termination.
-  // "cleanup_hook" points to a (global, or static member) function
-  // that is called for the object or array when it to be destroyed.
-  // It may perform any necessary cleanup specific for that object or
-  // its class.  "param" is passed as the second parameter to the
-  // "cleanup_hook" function; the first parameter is the object (or
-  // array) to be destroyed.  "cleanup_hook", for example, may delete
-  // the object (or array).  For OS's that do not have processes, this
-  // function is the same as <at_thread_exit>.  Returns 0 on success.
-  // On failure, returns -1 and sets errno to: EAGAIN if shutting
-  // down, ENOMEM if insufficient virtual memory, or EEXIST if the
-  // object (or array) had already been registered.
 
 #if 0 /* not implemented yet */
+  /// Similar to <at_exit>, except that the cleanup_hook is called
+  /// when the current thread exits instead of when the program terminates.
   static int at_thread_exit (void *object,
                              ACE_CLEANUP_FUNC cleanup_hook,
                              void *param);
-  // Similar to <at_exit>, except that the cleanup_hook is called
-  // when the current thread exits instead of when the program terminates.
 #endif /* 0 */
 
   enum Preallocated_Object
@@ -295,71 +297,85 @@ public:
   // ace/Managed_Object.h for information on accessing preallocated
   // arrays.
 
+  /**
+   * Accesses a default signal set used, for example, in ACE_Sig_Guard
+   * methods.
+   * Deprecated:  use ACE_Object_Manager::default_mask () instead.
+   */
   static ACE_Sig_Set &default_mask (void);
-  // Accesses a default signal set used, for example, in ACE_Sig_Guard
-  // methods.
-  // Deprecated:  use ACE_Object_Manager::default_mask () instead.
 
 private:
+  /// For at_exit support.
   ACE_OS_Exit_Info exit_info_;
-  // For at_exit support.
 
 #if !defined (ACE_LACKS_ACE_SVCCONF)
+  /// Preallocated objects collection.
   ACE_Object_Manager_Preallocations *preallocations_;
-  // Preallocated objects collection.
 
+  /// ACE_Service_Config signal handler.
   ACE_Sig_Adapter *ace_service_config_sig_handler_;
-  // ACE_Service_Config signal handler.
 #endif /* ! ACE_LACKS_ACE_SVCCONF */
 
+  /// Register an object or array for deletion at program termination.
+  /// See description of static version above for return values.
   int at_exit_i (void *object, ACE_CLEANUP_FUNC cleanup_hook, void *param);
-  // Register an object or array for deletion at program termination.
-  // See description of static version above for return values.
 
 #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0)
 public:
   // = The <get_singleton_lock> accessors are for internal
   // use by ACE_Singleton _only_.
 
+  /**
+   * Accesses an <ACE_Null_Mutex> to be used for construction of
+   * <ACE_Singletons>.  Returns 0, and the lock in the argument, on
+   * success; returns -1 on failure.
+   */
   static int get_singleton_lock (ACE_Null_Mutex *&);
-  // Accesses an <ACE_Null_Mutex> to be used for construction of
-  // <ACE_Singletons>.  Returns 0, and the lock in the argument, on
-  // success; returns -1 on failure.
 
+  /**
+   * Accesses a non-recursive <ACE_Thread_Mutex> to be used for
+   * construction of <ACE_Singletons>.  Returns 0, and the lock in the
+   * argument, on success; returns -1 on failure.
+   */
   static int get_singleton_lock (ACE_Thread_Mutex *&);
-  // Accesses a non-recursive <ACE_Thread_Mutex> to be used for
-  // construction of <ACE_Singletons>.  Returns 0, and the lock in the
-  // argument, on success; returns -1 on failure.
 
+  /**
+   * Accesses a non-recursive <ACE_Mutex> to be used for construction
+   * of <ACE_Singletons>.  Returns 0, and the lock in the argument, on
+   * success; returns -1 on failure.
+   */
   static int get_singleton_lock (ACE_Mutex *&);
-  // Accesses a non-recursive <ACE_Mutex> to be used for construction
-  // of <ACE_Singletons>.  Returns 0, and the lock in the argument, on
-  // success; returns -1 on failure.
 
+  /**
+   * Accesses a recursive <ACE_Recursive_Thread_Mutex> to be used for
+   * construction of <ACE_Singletons>.  Returns 0, and the lock in the
+   * argument, on success; returns -1 on failure.
+   */
   static int get_singleton_lock (ACE_Recursive_Thread_Mutex *&);
-  // Accesses a recursive <ACE_Recursive_Thread_Mutex> to be used for
-  // construction of <ACE_Singletons>.  Returns 0, and the lock in the
-  // argument, on success; returns -1 on failure.
 
+  /**
+   * Accesses a readers/writer <ACE_RW_Thread_Mutex> to be used for
+   * construction of <ACE_Singletons>.  Returns 0, and the lock in the
+   * argument, on success; returns -1 on failure.
+   */
   static int get_singleton_lock (ACE_RW_Thread_Mutex *&);
-  // Accesses a readers/writer <ACE_RW_Thread_Mutex> to be used for
-  // construction of <ACE_Singletons>.  Returns 0, and the lock in the
-  // argument, on success; returns -1 on failure.
 #endif /* ACE_MT_SAFE */
 
 public:
   // For internal use only by ACE_Managed_Objects.
 
+  /**
+   * Accessor to singleton instance.  Because static member functions
+   * are provided in the interface, this should not be public.  However,
+   * it is public so that ACE_Managed_Object<TYPE> can access it.
+   */
   static ACE_Object_Manager *instance (void);
-  // Accessor to singleton instance.  Because static member functions
-  // are provided in the interface, this should not be public.  However,
-  // it is public so that ACE_Managed_Object<TYPE> can access it.
 
+  /// Table of preallocated objects.
   static void *preallocated_object[ACE_PREALLOCATED_OBJECTS];
-  // Table of preallocated objects.
 
+  /// Table of preallocated arrays.
   static void *preallocated_array[ACE_PREALLOCATED_ARRAYS];
-  // Table of preallocated arrays.
 
 public:
   // Application code should not use these explicitly, so they're
@@ -370,19 +386,19 @@ public:
   ~ACE_Object_Manager (void);
 
 private:
+  /// Singleton pointer.
   static ACE_Object_Manager *instance_;
-  // Singleton pointer.
 
 #if defined (ACE_MT_SAFE) && (ACE_MT_SAFE != 0)
+  /// Lock that is used to guard internal structures.
   ACE_Recursive_Thread_Mutex *internal_lock_;
-  // Lock that is used to guard internal structures.
 
+  /// Null lock for guarding singleton creation.
   ACE_Cleanup_Adapter<ACE_Null_Mutex> *singleton_null_lock_;
-  // Null lock for guarding singleton creation.
 
+  /// Lock for guarding singleton creation, when Object_Manager
+  /// hasn't been started up, or has already been shut down.
   ACE_Cleanup_Adapter<ACE_Recursive_Thread_Mutex> *singleton_recursive_lock_;
-  // Lock for guarding singleton creation, when Object_Manager
-  // hasn't been started up, or has already been shut down.
 #endif /* ACE_MT_SAFE */
 
 #if defined (ACE_HAS_TSS_EMULATION)
@@ -404,23 +420,25 @@ private:
 
 class ACE_Recursive_Thread_Mutex;
 
+/**
+ * @class ACE_Static_Object_Lock
+ *
+ * @brief Provide an interface to access a global lock.
+ *
+ * This class is used to serialize the creation of static
+ * singleton objects.  It really isn't needed any more, because
+ * anyone can access ACE_STATIC_OBJECT_LOCK directly.  But, it
+ * is retained for backward compatibility.
+ */
 class ACE_Export ACE_Static_Object_Lock
 {
-  // = TITLE
-  //     Provide an interface to access a global lock.
-  //
-  // = DESCRIPTION
-  //     This class is used to serialize the creation of static
-  //     singleton objects.  It really isn't needed any more, because
-  //     anyone can access ACE_STATIC_OBJECT_LOCK directly.  But, it
-  //     is retained for backward compatibility.
 public:
+  /// Static lock access point.
   static ACE_Recursive_Thread_Mutex *instance (void);
-  // Static lock access point.
 
+  /// For use only by ACE_Object_Manager to clean up lock if it
+  /// what dynamically allocated.
   static void cleanup_lock (void);
-  // For use only by ACE_Object_Manager to clean up lock if it
-  // what dynamically allocated.
 };
 
 #endif /* ACE_HAS_THREADS */