F5/unison
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[Doxygen] various in src/core

Browse Source
This commit is contained in:
Peter D. Barnes, Jr.
2014-11-03 12:40:24 -08:00
parent ee641c723b
commit 1e1a1edbdc
15 changed files with 239 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
src/core/model/log.h
View File

@@ -165,6 +165,9 @@ void LogComponentDisableAll (enum LogLevel level);
* ns3::LogComponentDisable functions or with the NS_LOG
* environment variable.
*
* LogComponent names should be simple string tokens, _i.e._,
* "ArfWifiManager", not "ns3::ArfWifiManager".
*
* This macro should be placed within namespace ns3. If functions
* outside of namespace ns3 require access to logging, the preferred
* solution is to add the following 'using' directive at file scope,

4
src/core/model/random-variable-stream.h
View File

@@ -87,6 +87,10 @@ class RngStream;
class RandomVariableStream : public Object
{
public:
/**
* \brief Register this type.
* \return The object TypeId.
*/
static TypeId GetTypeId (void);
RandomVariableStream ();
virtual ~RandomVariableStream();

17
src/core/model/rng-seed-manager.cc
View File

@@ -28,11 +28,28 @@ namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("RngSeedManager");
/**
* \relates RngSeedManager
* The next random number generator stream number to use
* for automatic assignment.
*/
static uint64_t g_nextStreamIndex = 0;
/**
* \relates RngSeedManager
* The random number generator seed number global value.
*
* This is accessible as "--RngSeed" from CommandLine.
*/
static ns3::GlobalValue g_rngSeed ("RngSeed",
"The global seed of all rng streams",
ns3::IntegerValue(1),
ns3::MakeIntegerChecker<uint32_t> ());
/**
* \relates RngSeedManager
* The random number generator run number global value.
*
* This is accessible as "--RngRun" from CommandLine.
*/
static ns3::GlobalValue g_rngRun ("RngRun",
"The run number used to modify the global seed",
ns3::IntegerValue (1),

10
src/core/model/system-path.cc
View File

@@ -61,6 +61,16 @@ NS_LOG_COMPONENT_DEFINE ("SystemPath");
namespace SystemPath {
/**
* \ingroup systempath
* \brief Get the directory path for a file.
*
* This is an internal function (by virtue of not being
* declared in a \c .h file); the public API is FindSelfDirectory().
*
* \param path The full path to a file.
* \returns The full path to the containing directory.
*/
std::string Dirname (std::string path)
{
NS_LOG_FUNCTION (path);

25
src/core/model/system-path.h
View File

@@ -26,18 +26,34 @@
namespace ns3 {
/**
* \brief Encapsulate OS-specific functions to manipulate file and directory paths.
* \ingroup testing
* \defgroup systempath Host Filesystem
* \brief Encapsulate OS-specific functions to manipulate file
* and directory paths.
*
* The functions provided here are used mostly to implement the ns-3 test framework.
* The functions provided here are used mostly to implement
* the ns-3 test framework.
*/
/**
* \addtogroup core
* \see systempath
*/
/**
* \ingroup systempath
* \brief Namespace for various file and directory path functions.
*/
namespace SystemPath {
/**
* \ingroup systempath
* \return the directory in which the currently-executing binary is located
*/
std::string FindSelfDirectory (void);
/**
* \ingroup systempath
* \param left a path element
* \param right a path element
* \return a concatenation of the two input paths
@@ -45,6 +61,7 @@ namespace SystemPath {
std::string Append (std::string left, std::string right);
/**
* \ingroup systempath
* \param path a path
* \return a list of path elements that can be joined together again with
* the Join function.
@@ -53,6 +70,7 @@ namespace SystemPath {
std::list<std::string> Split (std::string path);
/**
* \ingroup systempath
* \param begin iterator to first element to join
* \param end iterator to last element to join
* \return a path that is a concatenation of all the input elements.
@@ -61,12 +79,14 @@ namespace SystemPath {
std::list<std::string>::const_iterator end);
/**
* \ingroup systempath
* \param path a path which identifies a directory
* \return a list of the filenames which are located in the input directory
*/
std::list<std::string> ReadFiles (std::string path);
/**
* \ingroup systempath
* \return a path which identifies a temporary directory.
*
* The returned path identifies a directory which does not exist yet
@@ -76,6 +96,7 @@ namespace SystemPath {
std::string MakeTemporaryDirectoryName (void);
/**
* \ingroup systempath
* \param path a path to a directory
*
* Create all the directories leading to path.

34
src/core/model/system-wall-clock-ms.h
View File

@@ -26,8 +26,12 @@
namespace ns3 {
/**
* \brief measure elapsed time in milliseconds
*
* \addtogroup core
* \see SystemWallClockMs
*/
/**
* \ingroup testing
* \brief Measure elapsed wall clock time in milliseconds.
*/
class SystemWallClockMs {
public:
@@ -41,39 +45,39 @@ public:
/**
* \brief Stop measuring the time since Start() was called.
* \returns the measured elapsed wall clock time (in milliseconds) since
* ns3::SystemWallClockMs::Start was invoked.
* Start() was invoked.
*
* It is possible to start a new measurement with ns3::SystemWallClockMs::Start
* after this method returns.
* It is possible to start a new measurement with Start() after
* this method returns.
*
* Returns int64_t to avoid dependency on clock_t in ns-3 code.
* Returns \c int64_t to avoid dependency on \c clock_t in ns-3 code.
*/
int64_t End (void);
/**
* \returns the measured elapsed wall clock time (in milliseconds) since
* ns3::SystemWallClockMs::Start was invoked.
* Start() was invoked.
*
* Returns int64_t to avoid dependency on clock_t in ns-3 code.
* Returns \c int64_t to avoid dependency on \c clock_t in ns-3 code.
*/
int64_t GetElapsedReal (void) const;
/**
* \returns the measured elapsed 'user' wall clock time (in milliseconds) since
* ns3::SystemWallClockMs::Start was invoked.
* \returns the measured elapsed 'user' wall clock time (in milliseconds)
* since Start() was invoked.
*
* Returns int64_t to avoid dependency on clock_t in ns-3 code.
* Returns \c int64_t to avoid dependency on \c clock_t in ns-3 code.
*/
int64_t GetElapsedUser (void) const;
/**
* \returns the measured elapsed 'system' wall clock time (in milliseconds) since
* ns3::SystemWallClockMs::Start was invoked.
* \returns the measured elapsed 'system' wall clock time (in milliseconds)
* since Start() was invoked.
*
* Returns int64_t to avoid dependency on clock_t in ns-3 code.
* Returns \c int64_t to avoid dependency on \c clock_t in ns-3 code.
*/
int64_t GetElapsedSystem (void) const;
private:
class SystemWallClockMsPrivate *m_priv;
class SystemWallClockMsPrivate *m_priv; //!< The implementation.
};
} // namespace ns3

54
src/core/model/test.h
View File

@@ -34,6 +34,15 @@
* \ingroup core
* \defgroup testing Testing
* \brief Tools to define and execute unit tests.
*
* This module lists the normal Testing API. Most of these
* macros forward to the implementation macros in testingimpl.
* You should generally use these macros only.
*/
/**
* \ingroup testing
* \defgroup testingimpl Testing Implementation
* \brief Internal implementation of the Testing system.
*/
//
@@ -89,7 +98,7 @@
// ===========================================================================
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual and expected (limit) value are equal and report
* and abort if not.
*/
@@ -144,7 +153,7 @@
NS_TEST_ASSERT_MSG_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual and expected (limit) value are equal and report
* and abort if not.
*/
@@ -202,7 +211,7 @@
NS_TEST_ASSERT_MSG_EQ_RETURNS_BOOL_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual and expected (limit) value are equal and report
* if not.
*
@@ -264,7 +273,7 @@
// ===========================================================================
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that actual and expected (limit) values are equal to plus
* or minus some tolerance and report and abort if not.
*/
@@ -348,7 +357,7 @@
NS_TEST_ASSERT_MSG_EQ_TOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that actual and expected (limit) values are equal to plus
* or minus some tolerance and report and abort if not.
*/
@@ -435,7 +444,7 @@
NS_TEST_ASSERT_MSG_EQ_TOL_RETURNS_BOOL_INTERNAL (actual, limit, tol, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that actual and expected (limit) values are equal to plus or minus
* some tolerance and report if not.
*
@@ -525,7 +534,7 @@
// ===========================================================================
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual and expected (limit) value are not equal and
* report and abort if not.
*/
@@ -579,7 +588,7 @@
NS_TEST_ASSERT_MSG_NE_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual and expected (limit) value are not equal and
* report and abort if not.
*/
@@ -636,7 +645,7 @@
NS_TEST_ASSERT_MSG_NE_RETURNS_BOOL_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual and expected (limit) value are not equal and
* report if not.
*
@@ -696,7 +705,7 @@
// ===========================================================================
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is less than a limit and report and abort
* if not.
*/
@@ -720,7 +729,7 @@
} while (false)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is less than or equal to a limit and report
* and abort if not.
*/
@@ -784,7 +793,7 @@
NS_TEST_ASSERT_MSG_LT_OR_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is less than a limit and report if not.
*
* Required to avoid use of return statement which allows use in methods
@@ -809,7 +818,7 @@
} while (false)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is less than or equal to a limit and report
* if not.
*
@@ -878,7 +887,7 @@
// ===========================================================================
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is greater than a limit and report and abort
* if not.
*/
@@ -902,7 +911,7 @@
} while (false)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is greater than or equal to a limit and
* report and abort if not.
*/
@@ -966,7 +975,7 @@
NS_TEST_ASSERT_MSG_GT_OR_EQ_INTERNAL (actual, limit, msg, __FILE__, __LINE__)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is greater than a limit and report if not.
*
* Required to avoid use of return statement which allows use in methods
@@ -991,7 +1000,7 @@
} while (false)
/**
* \ingroup testing
* \ingroup testingimpl
* \brief Test that an actual value is greater than a or equal to limit and
* report if not.
*
@@ -1058,6 +1067,7 @@
namespace ns3 {
/**
* \ingroup testing
* \brief Compare two double precision floating point numbers and declare them
* equal if they are within some epsilon of each other.
*
@@ -1156,11 +1166,19 @@ protected:
/**
* @{
* \internal
* The methods below are used only by test macros and should not
* be used by normal users.
*/
/**
* Log the failure of this TestCase.
*
* \param cond The test condition.
* \param actual Actual value of the test.
* \param limit Expected value of the test.
* \param message Message indicating the type of failure.
* \param file The file where the test failed.
* \param line The line number in \p file where the test failed.
*/
void ReportTestFailure (std::string cond, std::string actual,
std::string limit, std::string message,
@@ -1288,7 +1306,7 @@ private:
};
/**
* \ingroup testing
* \ingroup testingimpl
*
* \brief A runner to execute tests.
*/

30
src/core/model/type-name.cc
View File

@@ -21,23 +21,15 @@
namespace ns3 {
#define DEF_TYPE(x) \
template <> \
std::string TypeNameGet<x> (void) \
{ \
return # x; \
}
DEF_TYPE (uint8_t);
DEF_TYPE (uint16_t);
DEF_TYPE (uint32_t);
DEF_TYPE (uint64_t);
DEF_TYPE (int8_t);
DEF_TYPE (int16_t);
DEF_TYPE (int32_t);
DEF_TYPE (int64_t);
DEF_TYPE (float);
DEF_TYPE (double);
template <> std::string TypeNameGet< int8_t > (void) { return "int8_t" ; }
template <> std::string TypeNameGet< int16_t > (void) { return "int16_t" ; }
template <> std::string TypeNameGet< int32_t > (void) { return "int32_t" ; }
template <> std::string TypeNameGet< int64_t > (void) { return "int64_t" ; }
template <> std::string TypeNameGet< uint8_t > (void) { return "uint8_t" ; }
template <> std::string TypeNameGet< uint16_t> (void) { return "uint16_t"; }
template <> std::string TypeNameGet< uint32_t> (void) { return "uint32_t"; }
template <> std::string TypeNameGet< uint64_t> (void) { return "uint64_t"; }
template <> std::string TypeNameGet< float > (void) { return "float" ; }
template <> std::string TypeNameGet< double > (void) { return "double" ; }
} // namespace ns3

42
src/core/model/type-name.h
View File

@@ -25,29 +25,37 @@
namespace ns3 {
/**
* \ingroup attributeimpl
* Type name strings for numeric AttributeValue types.
*
* \tparam T The numeric type.
* \returns The numeric type name as a string.
*/
template <typename T>
std::string TypeNameGet (void)
{
return "unknown";
}
#define DEF_TYPE(x) \
template <> \
std::string TypeNameGet<x> (void)
DEF_TYPE (uint8_t);
DEF_TYPE (uint16_t);
DEF_TYPE (uint32_t);
DEF_TYPE (uint64_t);
DEF_TYPE (int8_t);
DEF_TYPE (int16_t);
DEF_TYPE (int32_t);
DEF_TYPE (int64_t);
DEF_TYPE (float);
DEF_TYPE (double);
#undef DEF_TYPE
/**
* \ingroup attributeimpl
* ns3::TypeNameGet(void) specializaton.
* \returns The numeric type name as a string.
* @{
*/
template <> std::string TypeNameGet< int8_t > (void);
template <> std::string TypeNameGet< int16_t > (void);
template <> std::string TypeNameGet< int32_t > (void);
template <> std::string TypeNameGet< int64_t > (void);
template <> std::string TypeNameGet< uint8_t > (void);
template <> std::string TypeNameGet< uint16_t> (void);
template <> std::string TypeNameGet< uint32_t> (void);
template <> std::string TypeNameGet< uint64_t> (void);
template <> std::string TypeNameGet< float > (void);
template <> std::string TypeNameGet< double > (void);
/**@}*/
} // namespace ns3
#endif /* TYPE_NAME_H */

19
src/core/model/unix-system-wall-clock-ms.cc
View File

@@ -28,20 +28,29 @@ namespace ns3 {
NS_LOG_COMPONENT_DEFINE ("SystemWallClockMsPrivate");
/**
* \ingroup testingimpl
* \brief System-dependent implementation for SystemWallClockMs
*/
class SystemWallClockMsPrivate {
public:
/** \copydoc SystemWallClockMs::Start() */
void Start (void);
/** \copydoc SystemWallClockMs::End() */
int64_t End (void);
/** \copydoc SystemWallClockMs::GetElapsedReal() */
int64_t GetElapsedReal (void) const;
/** \copydoc SystemWallClockMs::GetElapsedUser() */
int64_t GetElapsedUser (void) const;
/** \copydoc SystemWallClockMs::GetElapsedSystem() */
int64_t GetElapsedSystem (void) const;
private:
struct tms m_startTimes;
clock_t m_startTime;
int64_t m_elapsedReal;
int64_t m_elapsedUser;
int64_t m_elapsedSystem;
struct tms m_startTimes; //!< The native time structure.
clock_t m_startTime; //!< Native real time.
int64_t m_elapsedReal; //!< Elapsed real time, in ms.
int64_t m_elapsedUser; //!< Elapsed user time, in ms.
int64_t m_elapsedSystem; //!< Elapsed system time, in ms.
};
void

17
src/core/model/win32-system-wall-clock-ms.cc
View File

@@ -24,19 +24,28 @@
namespace ns3 {
/**
* \ingroup testingimpl
* \brief System-dependent implementation for SystemWallClockMs
*/
class SystemWallClockMsPrivate {
public:
/** \copydoc SystemWallClockMs::Start() */
void Start (void);
/** \copydoc SystemWallClockMs::End() */
int64_t End (void);
/** \copydoc SystemWallClockMs::GetElapsedReal() */
int64_t GetElapsedReal (void) const;
/** \copydoc SystemWallClockMs::GetElapsedUser() */
int64_t GetElapsedUser (void) const;
/** \copydoc SystemWallClockMs::GetElapsedSystem() */
int64_t GetElapsedSystem (void) const;
private:
clock_t m_startTime;
int64_t m_elapsedReal;
int64_t m_elapsedUser;
int64_t m_elapsedSystem;
clock_t m_startTime; //!< The wall clock start time.
int64_t m_elapsedReal; //!< Elapsed real time, in ms.
int64_t m_elapsedUser; //!< Elapsed user time, in ms.
int64_t m_elapsedSystem; //!< Elapsed system time, in ms.
};
void

5
src/internet/model/arp-l3-protocol.cc
View File

@@ -187,9 +187,10 @@ ArpL3Protocol::Receive (Ptr<NetDevice> device, Ptr<const Packet> p, uint16_t pro
NS_LOG_LOGIC (cache->GetInterface ()->GetAddress (i).GetLocal () << ", ");
}
/** \internal
/**
* \internal
* Note: we do not update the ARP cache when we receive an ARP request
* from an unknown node. See \bugid{107}
* from an unknown node. See \bugid{107}
*/
bool found = false;
for (uint32_t i = 0; i < cache->GetInterface ()->GetNAddresses (); i++)

50
src/wimax/model/default-traces.h
View File

@@ -19,25 +19,46 @@
* <amine.ismail@udcast.com>
*/
/**
* \brief this file represents default traces providing for each SNR value (1): the bit error rate BER (2), the block error
* rate BlcER(3), the standard deviation on block error rate (4) and the confidence interval (5 and 6) for a given
* modulation.
* It is made of 7 tables: one for each modulation and coding scheme. Each table is made of 6 columns (see (1) to (6) above).
* These traces are generated by an external OFDM simulator: It is based on an external mathematics and signal processing
* library IT++ and includes : a random block generator, a Reed Solomon (RS) coder, a convolutional coder, an interleaver, a 256
* FFT-based OFDM modulator, a multi-path channel simulator and an equalizer. The multipath channel is simulated using
* the TDL_channel class of the IT++ library.
*/
#ifndef WIMAX_DEFAULT_TRACES_H
#define WIMAX_DEFAULT_TRACES_H
namespace ns3 {
/**
* \brief These represent default traces, providing a number of
* parameters for each SNR value.
*
* The parameters provided are (in order):
*
* -# The SNR value,
* -# The bit error rate BER,
* -# The block error rate BlcERm,
* -# The standard deviation on block error rate,
* -# The lower bound confidence interval for a given modulation, and
* -# The upper bound confidence interval for a given modulation.
*
* It is made of 7 tables: one for each modulation and coding scheme.
* Each table is made of 6 columns, as listed above.
*
* These traces are generated by an external OFDM simulator: It is based
* on an external mathematics and signal processing library IT++ and includes:
*
* * A random block generator,
* * A Reed Solomon (RS) coder,
* * A convolutional coder,
* * an interleaver,
* * A 256 FFT-based OFDM modulator,
* * A multi-path channel simulator, and
* * An equalizer.
*
* The multipath channel is simulated using the TDL_channel class of
* the IT++ library.
*
* \relates ns3::SNRToBlockErrorRateManager
* \hideinitializer
* @{
*/
static const double modulation0[6][29] = {
{ 0.00, 0.10, 0.20, 0.30, 0.40, 0.50, 0.60, 0.70, 0.80, 0.90, 1.00, 1.10, 1.20, 1.30, 1.40, 1.50, 1.60, 1.70, 1.80,
@@ -833,6 +854,7 @@ static const double modulation6[6][626] = {
0.01943 }
};
/** @}*/
}
#endif /* WIMAX_DEFAULT_TRACES_H */

31
src/wimax/model/snr-to-block-error-rate-manager.h
View File

@@ -31,17 +31,26 @@ namespace ns3 {
/**
* \ingroup wimax
* \brief This class handles the SNR to BlcER traces. A path to a repository containing trace files should be provided.
* If no repository is provided the traces form default-traces.h will be loaded.
* A valid repository should contain 7 files, one for each modulation and coding scheme.
* The names of the files should respect the following format: modulation0.txt for modulation 0, modulation1.txt for
* modulation 1 and so on...
* The files format should be as follows
* SNR_value(1) BER(1) Blc_ER(1) STANDARD_DEVIATION(1) CONFIDENCE_INTERVAL1(1) CONFIDENCE_INTERVAL2(1)
* SNR_value(2) BER(2) Blc_ER(2) STANDARD_DEVIATION(2) CONFIDENCE_INTERVAL1(2) CONFIDENCE_INTERVAL2(2)
* ... ... ... ... ... ...
* ... ... ... ... ... ...
* SNR_value(n) BER(n) Blc_ER(n) STANDARD_DEVIATION(n) CONFIDENCE_INTERVAL1(n) CONFIDENCE_INTERVAL2(n)
* \brief This class handles the SNR to BlcER traces.
*
* A path to a repository containing trace files should be provided.
* If no repository is provided the traces from default-traces.h will be loaded.
* A valid repository should contain 7 files, one for each modulation
* and coding scheme.
*
* The names of the files should respect the following format:
* \c modulation<modulation-and-conding-index>.txt, _e.g._
* \c modulation0.txt, \c modulation1.txt, _etc._ for
* modulation 0, modulation 1, and so on...
*
* The file format is ASCII with six columns as follows:
*
* -# The SNR value,
* -# The bit error rate BER,
* -# The block error rate BlcERm,
* -# The standard deviation on block error rate,
* -# The lower bound confidence interval for a given modulation, and
* -# The upper bound confidence interval for a given modulation.
*/
class SNRToBlockErrorRateManager
{

5
utils/print-introspected-doxygen.cc
View File

@@ -538,6 +538,10 @@ PrintAllLogComponents (std::ostream & os)
os << "This is a list of all" << reference << "ns3::LogComponent instances.\n"
<< std::endl;
/**
* \todo Switch to a border-less table, so the file links align
* See http://www.stack.nl/~dimitri/doxygen/manual/htmlcmds.html
*/
os << listStart << std::endl;
LogComponent::ComponentList * logs = LogComponent::GetComponentList ();
LogComponent::ComponentList::const_iterator it;
@@ -545,6 +549,7 @@ PrintAllLogComponents (std::ostream & os)
{
std::string file = it->second->File ();
// Strip leading "../" related to depth in build directory
// since doxygen only sees the path starting with "src/", etc.
while (file.find ("../") == 0)
{
file = file.substr (3);