[Doxygen] Singleton and SimulationSingleton

src/core/model/simulation-singleton.h

@@ -20,27 +20,41 @@
 #ifndef SIMULATION_SINGLETON_H
 #define SIMULATION_SINGLETON_H
 
+/**
+ * \file
+ * \ingroup core
+ * ns3::SimulationSingleton declaration and template implementation.
+ */
+
 namespace ns3 {
 
 /**
+ * \ingroup core
  * This singleton class template ensures that the type
  * for which we want a singleton has a lifetime bounded
- * by the simulation lifetime. That it, the underlying
- * type will be automatically deleted upon a users' call
+ * by the simulation run lifetime. That it, the underlying
+ * type will be automatically deleted upon a call
  * to Simulator::Destroy.
+ *
+ * For a singleton with a lifetime bounded by the process,
+ * not the simulation run, see Singleton.
  */
 template <typename T>
 class SimulationSingleton
 {
 public:
   /**
-   * \returns The instance underlying this singleton.
+   * Get a pointer to the singleton instance.
    *
    * This instance will be automatically deleted when the
-   * user calls ns3::Simulator::Destroy.
+   * simulation is destroyed by a call to Simulator::Destroy.
+   *
+   * \returns A pointer to the singleton instance.
    */
   static T *Get (void);
+  
 private:
+  
   /**
    * Get the singleton object, creating a new one if it doesn't exist yet.
    *
@@ -51,13 +65,39 @@ private:
    * \returns The address of the pointer holding the static instance.
    */
   static T **GetObject (void);
-  /** Delete the underlying object. */
+  
+  /** Delete the static instance. */
   static void DeleteObject (void);
+
+  /**
+   * \name %Singleton pattern
+   * Private constructor, copy and assignment operator.
+   *
+   *  Note these do not have to be implemented, since they are
+   *  never called.
+   */
+  /**@{*/
+  /** Default constructor */
+  SimulationSingleton<T> (void);
+  
+  /** Copy constructor. */
+  SimulationSingleton<T> (const SimulationSingleton<T> &);
+  /**
+   * Assignment.
+   * \returns The Singleton.
+   */
+  SimulationSingleton<T> operator = (const SimulationSingleton<T> &);
+  /**@}*/
+
 };
 
 } // namespace ns3
 
 
+/********************************************************************
+ *  Implementation of the templates declared above.
+ ********************************************************************/
+
 #include "simulator.h"
 
 namespace ns3 {

src/core/model/singleton.h

@@ -20,29 +20,76 @@
 #ifndef SINGLETON_H
 #define SINGLETON_H
 
+/**
+ * \file
+ * \ingroup core
+ * ns3::Singleton declaration and template implementation.
+ */
+
 namespace ns3 {
 
 /**
- * \brief a template singleton
+ * \ingroup core
+ * \brief A template singleton
  *
  * This template class can be used to implement the singleton pattern.
  * The underlying object will be destroyed automatically when the process
- * exits. Note that, if you call Singleton::Get again after the object has
+ * exits.
+ *
+ * For a singleton whose lifetime is bounded by the simulation run,
+ * not the process, see SimulationSingleton.
+ *
+ * \note If you call Get() again after the object has
  * been destroyed, the object will be re-created which will result in a
  * memory leak as reported by most memory leak checkers. It is up to the
- * user to ensure that Singleton::Get is never called from a static variable
+ * user to ensure that Get() is never called from a static variable
  * finalizer.
  */
 template <typename T>
 class Singleton
 {
 public:
+  /**
+   * Get a pointer to the singleton instance.
+   *
+   * The instance will be automatically deleted when
+   * the process exits.
+   *
+   * \return A pointer to the singleton instance.
+   */
   static T *Get (void);
 
+private:
+
+  /**
+   * \name %Singleton pattern
+   * Private constructor, copy and assignment operator.
+   *
+   *  Note these do not have to be implemented, since they are
+   *  never called.
+   */
+  /**@{*/
+  /** Default constructor */
+  Singleton<T> (void);
+  
+  /** Copy constructor. */
+  Singleton<T> (const Singleton<T> &);
+  /**
+   * Assignment.
+   * \returns The Singleton.
+   */
+  Singleton<T> operator = (const Singleton<T> &);
+  /**@}*/
+
 };
 
 } // namespace ns3
 
+
+/********************************************************************
+ *  Implementation of the templates declared above.
+ ********************************************************************/
+
 namespace ns3 {
 
 template <typename T>