--- a/src/stats/helper/file-helper.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/helper/file-helper.h Fri Nov 15 15:08:38 2013 -0500 @@ -133,12 +133,13 @@ /** * \param probeName the probe's name. - * + * \return Ptr to the probe * \brief Gets the specified probe. */ Ptr GetProbe (std::string probeName) const; /** + * \return Ptr to a FileAggregator object * \brief Gets the single aggregator that is always constructed. * * This function is non-const because an aggregator may be lazily @@ -149,7 +150,7 @@ /** * \param aggregatorName name for aggregator. * \param outputFileName name of output file to write. - * + * \return Ptr to a FileAggregator object * \brief Gets one of the multiple aggregators from the map. * * This function is non-const because an aggregator may be lazily --- a/src/stats/helper/gnuplot-helper.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/helper/gnuplot-helper.h Fri Nov 15 15:08:38 2013 -0500 @@ -139,12 +139,13 @@ /** * \param probeName the probe's name. - * + * \return Ptr to probe * \brief Gets the specified probe. */ Ptr GetProbe (std::string probeName) const; /** + * \return Ptr to GnuplotAggregator object * \brief Gets the aggregator. * * This function is non-const because an aggregator may be lazily --- a/src/stats/model/basic-data-calculators.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/basic-data-calculators.h Fri Nov 15 15:08:38 2013 -0500 @@ -31,6 +31,12 @@ * */ +/** + * \ingroup stats + * \class MinMaxAvgTotalCalculator + * \brief Template class MinMaxAvgTotalCalculator + * + */ //------------------------------------------------------------ //-------------------------------------------- template @@ -40,36 +46,75 @@ MinMaxAvgTotalCalculator(); virtual ~MinMaxAvgTotalCalculator(); + /** + * Updates all variables of MinMaxAvgTotalCalculator + * \param i value of type T to use for updating the calculator + */ void Update (const T i); + /** + * Reinitializes all variables of MinMaxAvgTotalCalculator + */ void Reset (); virtual void Output (DataOutputCallback &callback) const; + /** + * Returns the count + * \return Count + */ long getCount () const { return m_count; } + /** + * Returns the sum + * \return Total + */ double getSum () const { return m_total; } + /** + * Returns the minimum value + * \return Min + */ double getMin () const { return m_min; } + /** + * Returns the maximum value + * \return Max + */ double getMax () const { return m_max; } + /** + * Returns the mean value + * \return Mean + */ double getMean () const { return m_meanCurr; } + /** + * Returns the standard deviation + * \return Standard deviation + */ double getStddev () const { return std::sqrt (m_varianceCurr); } + /** + * Returns the current variance + * \return Variance + */ double getVariance () const { return m_varianceCurr; } + /** + * Returns the sum of squares + * \return Sum of squares + */ double getSqrSum () const { return m_squareTotal; } protected: virtual void DoDispose (void); - uint32_t m_count; + uint32_t m_count; /// Count value of MinMaxAvgTotalCalculator - T m_total; - T m_squareTotal; - T m_min; - T m_max; + T m_total; /// Total value of MinMaxAvgTotalCalculator + T m_squareTotal; /// Sum of squares value of MinMaxAvgTotalCalculator + T m_min; /// Minimum value of MinMaxAvgTotalCalculator + T m_max; /// Maximum value of MinMaxAvgTotalCalculator - double m_meanCurr; - double m_sCurr; - double m_varianceCurr; + double m_meanCurr; /// Current mean of MinMaxAvgTotalCalculator + double m_sCurr; /// Current s of MinMaxAvgTotalCalculator + double m_varianceCurr; /// Current variance of MinMaxAvgTotalCalculator - double m_meanPrev; - double m_sPrev; + double m_meanPrev; /// Previous mean of MinMaxAvgTotalCalculator + double m_sPrev; /// Previous s of MinMaxAvgTotalCalculator // end MinMaxAvgTotalCalculator }; @@ -197,6 +242,8 @@ /** * \ingroup stats + * \class CounterCalculator + * \brief Template class CounterCalculator * */ //------------------------------------------------------------ @@ -207,17 +254,32 @@ CounterCalculator(); virtual ~CounterCalculator(); + /** + * Increments count by 1 + */ void Update (); + /** + * Increments count by i + * \param i value of type T to increment count + */ void Update (const T i); + /** + * Returns the count of the CounterCalculator + * \return Count as a value of type T + */ T GetCount () const; + /** + * Outputs the data based on the provided callback + * \param callback + */ virtual void Output (DataOutputCallback &callback) const; protected: virtual void DoDispose (void); - T m_count; + T m_count; /// Count value of CounterCalculator // end CounterCalculator }; --- a/src/stats/model/data-calculator.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/data-calculator.h Fri Nov 15 15:08:38 2013 -0500 @@ -26,11 +26,24 @@ #include "ns3/simulator.h" namespace ns3 { -extern const double NaN; + +extern const double NaN; /// Stored representation of NaN + +/** + * \brief true if x is NaN + * \param x + * \return whether x is NaN + */ inline bool isNaN (double x) { return x != x; } class DataOutputCallback; +/** + * \ingroup stats + * \class StatisticalSummary + * \brief Abstract class for calculating statistical data + * + */ class StatisticalSummary { public: /** @@ -40,48 +53,62 @@ { } /** - * Returns the number of the observations. + * Returns the number of observations. + * \return Number of observations */ virtual long getCount () const = 0; /** * Returns the sum of the values. + * \return Sum of values * @see getWeightedSum() */ virtual double getSum () const = 0; /** * Returns the sum of the squared values. + * \return Sum of squared values * @see getWeightedSqrSum() */ virtual double getSqrSum () const = 0; /** * Returns the minimum of the values. + * \return Minimum of values */ virtual double getMin () const = 0; /** * Returns the maximum of the values. + * \return Maximum of values */ virtual double getMax () const = 0; /** * Returns the mean of the (weighted) observations. + * \return Mean of (weighted) observations */ virtual double getMean () const = 0; /** * Returns the standard deviation of the (weighted) observations. + * \return Standard deviation of (weighted) observations */ virtual double getStddev () const = 0; /** * Returns the variance of the (weighted) observations. + * \return Variance of (weighted) observations */ virtual double getVariance () const = 0; }; +/** + * \ingroup stats + * \class DataCalculator + * \brief Calculates data during a simulation + * + */ //------------------------------------------------------------ //-------------------------------------------- class DataCalculator : public Object { @@ -89,26 +116,65 @@ DataCalculator(); virtual ~DataCalculator(); + /** + * Returns whether the DataCalculator is enabled + * \return true if DataCalculator is enabled + */ bool GetEnabled () const; + + /** + * Enables DataCalculator when simulation starts + */ void Enable (); + + /** + * Disables DataCalculator when simulation stops + */ void Disable (); + /** + * Sets the DataCalculator key to the provided key + * \param key Key value as a string + */ void SetKey (const std::string key); + /** + * Gets the DataCalculator key + * \return Key value as a string + */ std::string GetKey () const; + /** + * Sets the DataCalculator context to the provided context + * \param context Context value as a string + */ void SetContext (const std::string context); + /** + * Gets the DataCalculator context + * \return Context value as a string + */ std::string GetContext () const; + /** + * Starts DataCalculator at a given time in the simulation + * \param startTime + */ virtual void Start (const Time& startTime); + /** + * Stops DataCalculator at a given time in the simulation + * \param stopTime + */ virtual void Stop (const Time& stopTime); + /** + * Outputs data based on the provided callback + * \param callback + */ virtual void Output (DataOutputCallback &callback) const = 0; protected: - bool m_enabled; // Descendant classes *must* check & respect m_enabled! + bool m_enabled; /// Descendant classes *must* check & respect m_enabled! - std::string m_key; - std::string m_context; + std::string m_key; /// Key value + std::string m_context; /// Context value virtual void DoDispose (void); --- a/src/stats/model/data-collection-object.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/data-collection-object.h Fri Nov 15 15:08:38 2013 -0500 @@ -40,8 +40,9 @@ DataCollectionObject (); virtual ~DataCollectionObject (); - /// Set the status of an individual object. + /// Set the status of an individual object. void Enable (void); + /// Unset the status of an individual object. void Disable (void); /// Check the status of an individual object. --- a/src/stats/model/data-collector.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/data-collector.h Fri Nov 15 15:08:38 2013 -0500 @@ -36,38 +36,108 @@ //------------------------------------------------------------ //-------------------------------------------- +/** + * List of Ptrs to DataCalculator objects + */ typedef std::list > DataCalculatorList; +/** + * List of pairs of strings representing metadata + */ typedef std::list > MetadataList; /** * \ingroup stats - * + * \class DataCollector + * \brief Collects data */ class DataCollector : public Object { public: DataCollector(); virtual ~DataCollector(); + /** + * Provide specific parameters to the DataCollector + * \param experiment Label for the experiment + * \param strategy Label for the strategy + * \param input Label for the input + * \param runID Label for the runID + * \param description Description + */ void DescribeRun (std::string experiment, std::string strategy, std::string input, std::string runID, std::string description = ""); + /** + * Return the experiment label + * \return Experiment label + */ std::string GetExperimentLabel () const { return m_experimentLabel; } + /** + * Return the strategy label + * \return Strategy label + */ std::string GetStrategyLabel () const { return m_strategyLabel; } + /** + * Return the input label + * \return Input label + */ std::string GetInputLabel () const { return m_inputLabel; } + /** + * Return the runID label + * \return Run label + */ std::string GetRunLabel () const { return m_runLabel; } + /** + * Return the description label + * \return Description label + */ std::string GetDescription () const { return m_description; } + /** + * Add the key and the value as a pair of strings to the metadata list + * \param key Key value to include + * \param value Value to include of type string + */ void AddMetadata (std::string key, std::string value); + /** + * Add the key and the value as a pair of strings to the metadata list + * \param key Key value to include + * \param value Value to include of type double + */ void AddMetadata (std::string key, double value); + /** + * Add the key and the value as a pair of strings to the metadata list + * \param key Key value to include + * \param value Value to include of type uint32_t + */ void AddMetadata (std::string key, uint32_t value); + /** + * Returns an iterator to the beginning of the metadata list + * \return Iterator pointing to the first value of the metadata list + */ MetadataList::iterator MetadataBegin (); + /** + * Returns an iterator to the past-the-end of the metadata list + * \return Iterator pointing to the past-the-end element of the metadata list + */ MetadataList::iterator MetadataEnd (); + /** + * Add a DataCalculator object to the DataCollector + * \param datac DataCalculator object to be added + */ void AddDataCalculator (Ptr datac); + /** + * Returns an iterator to the beginning of the DataCalculator list + * \return Iterator pointing to the first value of the DataCalculator list + */ DataCalculatorList::iterator DataCalculatorBegin (); + /** + * Returns an iterator to the past-the-end of the DataCalculator list + * \return Iterator pointing to the past-the-end element of the DataCalculator list + */ DataCalculatorList::iterator DataCalculatorEnd (); protected: --- a/src/stats/model/data-output-interface.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/data-output-interface.h Fri Nov 15 15:08:38 2013 -0500 @@ -33,6 +33,8 @@ //-------------------------------------------- /** * \ingroup stats + * \class DataCollector + * \brief Abstract Data Output Interface class * */ class DataOutputInterface : public Object { @@ -40,47 +42,100 @@ DataOutputInterface(); virtual ~DataOutputInterface(); + /** + * Outputs information from the provided DataCollector + * \param dc DataCollector object + */ virtual void Output (DataCollector &dc) = 0; + /** + * Sets the DataOutputInterface prefix to the provided prefix + * \param File prefix as a string + */ void SetFilePrefix (const std::string prefix); + /** + * Gets the file prefix of the DataOutputInterface + * \return File prefix as a string + */ std::string GetFilePrefix () const; protected: virtual void DoDispose (); - std::string m_filePrefix; + std::string m_filePrefix; /// File prefix for the DataOutputInterface // end class DataOutputInterface }; /** * \ingroup stats + * \class DataOutputCallback + * \brief Callback class for the DataOutput classes * */ class DataOutputCallback { public: + /** + * Destructor + */ virtual ~DataOutputCallback() {} + /** + * Outputs the data from the specified StatisticalSummary + * \param key Key value of a DataCalculator + * \param variable Name of the variable for which statistics are being provided + * \param statSum Pointer to a StatisticalSummary object + */ virtual void OutputStatistic (std::string key, std::string variable, const StatisticalSummary *statSum) = 0; + /** + * Associates the integer value with the variable name for a specific output format + * \param key Key value of a DataCalculator + * \param variable Name of the variable for which statistics are being provided + * \param val Value to be stored + */ virtual void OutputSingleton (std::string key, std::string variable, int val) = 0; + /** + * Associates the uint32_t value with the variable name for a specific output format + * \param key Key value of a DataCalculator + * \param variable Name of the variable for which statistics are being provided + * \param val Value to be stored + */ virtual void OutputSingleton (std::string key, std::string variable, uint32_t val) = 0; + /** + * Associates the double value with the variable name for a specific output format + * \param key Key value of a DataCalculator + * \param variable Name of the variable for which statistics are being provided + * \param val Value to be stored + */ virtual void OutputSingleton (std::string key, std::string variable, double val) = 0; + /** + * Associates the string value with the variable name for a specific output format + * \param key Key value of a DataCalculator + * \param variable Name of the variable for which statistics are being provided + * \param val Value to be stored + */ virtual void OutputSingleton (std::string key, std::string variable, std::string val) = 0; + /** + * Associates the Time value with the variable name for a specific output format + * \param key Key value of a DataCalculator + * \param variable Name of the variable for which statistics are being provided + * \param val Value to be stored + */ virtual void OutputSingleton (std::string key, std::string variable, Time val) = 0; --- a/src/stats/model/get-wildcard-matches.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/get-wildcard-matches.h Fri Nov 15 15:08:38 2013 -0500 @@ -30,6 +30,7 @@ * \param matchedPath the path that matched the Config path. * \param wildcardSeparator the text to put betwen the wildcard * matches. By default, a space is used. + * \return String value of text matches * * \brief Returns the text matches from the matched path for each of * the wildcards in the Config path, separated by the wild card --- a/src/stats/model/gnuplot.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/gnuplot.h Fri Nov 15 15:08:38 2013 -0500 @@ -41,6 +41,7 @@ /** * Reference-counting copy constructor. + * \param original Original GnuPlotDataset */ GnuplotDataset (const GnuplotDataset& original); @@ -51,6 +52,8 @@ /** * Reference-counting assignment operator. + * \param original Right-hand side of assignment operator + * \return Copy of original GnuplotDataset */ GnuplotDataset& operator= (const GnuplotDataset& original); @@ -101,6 +104,7 @@ }; /** + * \class Gnuplot2dDataset * \brief Class to represent a 2D points plot. Set the line or points style * using SetStyle() and set points using Add(). */ @@ -361,7 +365,8 @@ /** * Crude attempt to auto-detect the correct terminal setting by inspecting * the filename's extension. - * \param filename output file name + * \param filename output filename + * \return File extension of the provided filename */ static std::string DetectTerminal (const std::string& filename); --- a/src/stats/model/omnet-data-output.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/omnet-data-output.h Fri Nov 15 15:08:38 2013 -0500 @@ -32,6 +32,8 @@ //-------------------------------------------- /** * \ingroup stats + * \class OmnetDataOutput + * \brief Outputs data in a format compatible with OMNeT library and framework * */ class OmnetDataOutput : public DataOutputInterface { --- a/src/stats/model/sqlite-data-output.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/sqlite-data-output.h Fri Nov 15 15:08:38 2013 -0500 @@ -35,7 +35,8 @@ //-------------------------------------------- /** * \ingroup stats - * + * \class SqliteDataOutput + * \brief Outputs data in a format compatible with SQLite */ class SqliteDataOutput : public DataOutputInterface { public: --- a/src/stats/model/time-data-calculators.h Fri Nov 15 11:20:38 2013 +0100 +++ a/src/stats/model/time-data-calculators.h Fri Nov 15 15:08:38 2013 -0500 @@ -44,15 +44,25 @@ TimeMinMaxAvgTotalCalculator(); virtual ~TimeMinMaxAvgTotalCalculator(); + /** + * Updates all variables of TimeMinMaxAvgTotalCalculator + * \param i value of type Time to use for updating the calculator + */ void Update (const Time i); + /** + * Outputs data based on the provided callback + * \param callback + */ virtual void Output (DataOutputCallback &callback) const; protected: virtual void DoDispose (void); - uint32_t m_count; - Time m_total, m_min, m_max; + uint32_t m_count; /// Count value of TimeMinMaxAvgTotalCalculator + Time m_total; /// Total value of TimeMinMaxAvgTotalCalculator + Time m_min; /// Minimum value of TimeMinMaxAvgTotalCalculator + Time m_max; /// Maximum value of TimeMinMaxAvgTotalCalculator // end class TimeMinMaxAvgTotalCalculator };