[Doxygen] src/core

doc/doxygen.warnings.report.sh

@@ -2,7 +2,7 @@
 
 # Process doxygen.warnings.log to generate sorted list of top offenders
 
-# Flag to skip running doxygen
+# Flag to skip the build and running doxygen, and just analyze the log
 skipdoxy=${1:-""}
 
 DIR=`dirname $0`

doc/modules

@@ -1,8 +1,8 @@
 /**
  * @anchor modules_anchor
  *
- * @defgroup constructs C++ Constructs Used by All Modules
- * \brief These are C++ constructs defined by the modules.
+ * @defgroup constructs Introspected Lists
+ * \brief These are lists of useful items found by examining the type system.
  *
  * @defgroup constants Constants
  * @brief Constants you can change

src/core/model/command-line.h

@@ -47,36 +47,49 @@ namespace ns3 {
  * arguments: programs can register new arguments with
  * CommandLine::AddValue.
  *
+ * In use, arguments are given in the form
+ * \code
+ *   --arg=value --toggle
+ * \endcode
+ * Most arguments expect a value, as in the first form, \c --arg=value.
+ * Toggles, corresponding to boolean arguments, can be given in any of
+ * the forms
+ * \code
+ *   --toggle-1 --toggle-2=1 --toggle-3=t --toggle-4=true
+ * \endcode
+ * all of which set the corresponding boolean variable to true.
+ *
  * In addition, this class can be used to set the
- * 'initial value' of every attribute in the system with the
+ * initial value of every attribute in the system with the 
+ * \c --TypeIdName::AttributeName=value syntax, for example
  * \code
- *   --TypeIdName::AttributeName=value
+ *   --Application::StartTime=3s
  * \endcode
- * syntax, and it can be used to set the value of every GlobalValue
- * in the system with the
+ *
+ * This class can also be used to set the value of every GlobalValue
+ * in the system with the \c --GlobalValueName=value syntax, for example
  * \code
- *   --GlobalValueName=value
+ *   --SchedulerType=HeapScheduler
  * \endcode
- * syntax.
  *
  * A simple example is in \c src/core/example/command-line-example.cc
  * The heart of that example is this code:
  *
  * \code
- *  int         val1 = 1;
- *  bool        val2 = false;
- *  std::string val3 = "";
+ *  int         var1 = 1;
+ *  bool        var2 = false;
+ *  std::string var3 = "";
  *  
  *  CommandLine cmd;
  *  cmd.Usage ("CommandLine example program.\n"
  *             "\n"
  *             "This little program demonstrates how to use CommandLine.");
- *  cmd.AddValue ("val1", "an int argument",       val1);
- *  cmd.AddValue ("val2", "a bool argument",       val2);
- *  cmd.AddValue ("val3", "a string argument",     val3);
- *  cmd.AddValue ("val4", "a string via callback", MakeCallback (SetVal4));
+ *  cmd.AddValue ("val1", "an int argument",          val1);
+ *  cmd.AddValue ("val2", "a bool argument",          val2);
+ *  cmd.AddValue ("val3", "a string argument",        val3);
  *  cmd.Parse (argc, argv);
  * \endcode
+ * after which it prints the values of each variable.
  *
  * Here is the output from a few runs of that program:
  *
@@ -84,14 +97,12 @@ namespace ns3 {
  *   $ ./waf --run="command-line-example"
  *   val1:   1
  *   val2:   0
- *   val3:   "val3 default"
- *   val4:   "val4 default"
+ *   val3:   ""
  *
- *   $ ./waf --run="command-line-example --val1=2 --val2 --val3=Hello --val4=World"
+ *   $ ./waf --run="command-line-example --val1=2 --val2 --val3=Hello"
  *   val1:   2
  *   val2:   1
  *   val3:   "Hello"
- *   val4:   "World"
  *   
  *   $ ./waf --run="command-line-example --help"
  *   ns3-dev-command-line-example-debug [Program Arguments] [General Arguments]
@@ -101,10 +112,9 @@ namespace ns3 {
  *   This little program demonstrates how to use CommandLine.
  *   
  *   Program Arguments:
- *       --val1: an int argument
- *       --val2: a bool argument
- *       --val3: a string argument
- *       --val4: a string via callback
+ *       --val1:     an int argument
+ *       --val2:     a bool argument
+ *       --val3:     a string argument
  *   
  *   General Arguments:
  *       --PrintGlobals:              Print the list of globals.

src/core/model/event-id.h

@@ -29,7 +29,7 @@ namespace ns3 {
 class EventImpl;
 
 /**
- * \ingroup core
+ * \ingroup events
  * \brief an identifier for simulation events.
  *
  * Each EventId identifies a unique event scheduled with one

src/core/model/event-impl.h

@@ -26,7 +26,7 @@
 namespace ns3 {
 
 /**
- * \ingroup core
+ * \ingroup events
  * \brief a simulation event
  *
  * Each subclass of this base class represents a simulation event. The

src/core/model/object-base.h

@@ -55,8 +55,14 @@ class AttributeConstructionList;
 class ObjectBase
 {
 public:
+  /**
+   * Get the type ID.
+   */
   static TypeId GetTypeId (void);
 
+  /**
+   * Virtual destructor
+   */
   virtual ~ObjectBase ();
 
   /**

src/core/model/object.h

@@ -63,6 +63,9 @@ struct ObjectDeleter
 class Object : public SimpleRefCount<Object,ObjectBase,ObjectDeleter>
 {
 public:
+  /**
+   * Get the type ID.
+   */
   static TypeId GetTypeId (void);
 
   /**
@@ -90,9 +93,9 @@ public:
     Ptr<const Object> Next (void);
 private:
     friend class Object;
-    AggregateIterator (Ptr<const Object> object);
-    Ptr<const Object> m_object;
-    uint32_t m_current;
+    AggregateIterator (Ptr<const Object> object);  //!< Constructor
+    Ptr<const Object> m_object;                    //!< Parent Object
+    uint32_t m_current;                            //!< Current position in parent's aggegrates
   };
 
   Object ();
@@ -241,8 +244,27 @@ private:
     Object *buffer[1];
   };
 
+  /**
+   * Find an object of TypeId tid in the aggregates of this Object.
+   *
+   * \param tid the TypeId we're looking for
+   * \return the matching Object, if it is found
+   */
   Ptr<Object> DoGetObject (TypeId tid) const;
+  /**
+   * \return is reference count non zero
+   */
   bool Check (void) const;
+  /**
+   * \return Do any of our aggregates have non zero reference count?
+   *
+   * In some cases, when an event is scheduled against a subclass of
+   * Object, and if no one owns a reference directly to this object, the
+   * object is alive, has a refcount of zero and the method ran when the
+   * event expires runs against the raw pointer which means that we are
+   * manipulating an object with a refcount of zero.  So, instead we
+   * check the aggregate reference count.
+   */
   bool CheckLoose (void) const;
   /**
    * \param tid an TypeId
@@ -262,6 +284,12 @@ private:
   */
   void Construct (const AttributeConstructionList &attributes);
 
+  /**
+   * Keep the list of aggregates in most-recently-used order
+   *
+   * \param aggregates the list of aggregated objects
+   * \param i the most recently used entry in the list
+   */
   void UpdateSortedArray (struct Aggregates *aggregates, uint32_t i) const;
   /**
    * Attempt to delete this object. This method iterates

src/core/model/scheduler.h

@@ -30,7 +30,11 @@ class EventImpl;
 
 /**
  * \ingroup core
- * \defgroup scheduler Scheduler
+ * \defgroup scheduler Scheduler and Events
+ */
+/**
+ * \ingroup scheduler
+ * \defgroup events Events
  */
 /**
  * \ingroup scheduler
@@ -55,12 +59,14 @@ class Scheduler : public Object
 public:
   static TypeId GetTypeId (void);
 
+  /** \ingroup events */
   struct EventKey
   {
     uint64_t m_ts;
     uint32_t m_uid;
     uint32_t m_context;
   };
+  /** \ingroup events */
   struct Event
   {
     EventImpl *impl;

src/core/model/simple-ref-count.h

@@ -31,6 +31,7 @@
 namespace ns3 {
 
 /**
+ * \ingroup ptr
  * \brief A template-based reference counting class
  *
  * This template can be used to give reference-counting powers
@@ -63,12 +64,21 @@ template <typename T, typename PARENT = empty, typename DELETER = DefaultDeleter
 class SimpleRefCount : public PARENT
 {
 public:
+  /**
+   * Constructor
+   */
   SimpleRefCount ()
     : m_count (1)
   {}
+  /**
+   * Copy constructor
+   */
   SimpleRefCount (const SimpleRefCount &o)
     : m_count (1)
   {}
+  /**
+   * Assignment
+   */
   SimpleRefCount &operator = (const SimpleRefCount &o)
   {
     return *this;
@@ -108,6 +118,9 @@ public:
     return m_count;
   }
 
+  /**
+   *  Noop
+   */
   static void Cleanup (void) {}
 private:
   // Note we make this mutable so that the const methods can still