From 0ae8b1cb8d612f6994e16bd28ec26fa4f848af88 Mon Sep 17 00:00:00 2001 From: "Peter D. Barnes, Jr." Date: Wed, 24 Jul 2013 17:15:33 -0700 Subject: [PATCH] [Doxygen] src/core --- doc/doxygen.warnings.report.sh | 2 +- doc/modules | 4 +-- src/core/model/command-line.h | 52 ++++++++++++++++++------------- src/core/model/event-id.h | 2 +- src/core/model/event-impl.h | 2 +- src/core/model/object-base.h | 6 ++++ src/core/model/object.h | 34 ++++++++++++++++++-- src/core/model/scheduler.h | 8 ++++- src/core/model/simple-ref-count.h | 13 ++++++++ 9 files changed, 93 insertions(+), 30 deletions(-) diff --git a/doc/doxygen.warnings.report.sh b/doc/doxygen.warnings.report.sh index 45dd116bc..7865fd5c8 100755 --- a/doc/doxygen.warnings.report.sh +++ b/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` diff --git a/doc/modules b/doc/modules index 62974397e..11d7e1eb8 100644 --- a/doc/modules +++ b/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 diff --git a/src/core/model/command-line.h b/src/core/model/command-line.h index 6fee0f900..ba13248ad 100644 --- a/src/core/model/command-line.h +++ b/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. diff --git a/src/core/model/event-id.h b/src/core/model/event-id.h index c9cf4c396..5bad1e19e 100644 --- a/src/core/model/event-id.h +++ b/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 diff --git a/src/core/model/event-impl.h b/src/core/model/event-impl.h index 9eef400f2..8949894a8 100644 --- a/src/core/model/event-impl.h +++ b/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 diff --git a/src/core/model/object-base.h b/src/core/model/object-base.h index f93cd9b4c..a3cc4ac68 100644 --- a/src/core/model/object-base.h +++ b/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 (); /** diff --git a/src/core/model/object.h b/src/core/model/object.h index 35311d79c..87e1edbd7 100644 --- a/src/core/model/object.h +++ b/src/core/model/object.h @@ -63,6 +63,9 @@ struct ObjectDeleter class Object : public SimpleRefCount { public: + /** + * Get the type ID. + */ static TypeId GetTypeId (void); /** @@ -90,9 +93,9 @@ public: Ptr Next (void); private: friend class Object; - AggregateIterator (Ptr object); - Ptr m_object; - uint32_t m_current; + AggregateIterator (Ptr object); //!< Constructor + Ptr 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 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 diff --git a/src/core/model/scheduler.h b/src/core/model/scheduler.h index c7ac05485..a66fa341f 100644 --- a/src/core/model/scheduler.h +++ b/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; diff --git a/src/core/model/simple-ref-count.h b/src/core/model/simple-ref-count.h index fa0b15146..55e54628b 100644 --- a/src/core/model/simple-ref-count.h +++ b/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