From 321b953877e3a01d418c680865aef07fd82c8a29 Mon Sep 17 00:00:00 2001 From: Mathieu Lacage Date: Mon, 10 Mar 2008 14:05:26 -0700 Subject: [PATCH] doxygen doc --- src/core/attribute-helper.h | 106 +++++++++++++++++++++++++++++++++++- src/core/boolean.h | 6 ++ src/core/command-line.h | 28 ++++++++++ src/core/double.h | 6 ++ src/core/enum.h | 6 ++ src/core/global-value.h | 56 ++++++++++++++++++- src/core/integer.h | 7 +++ src/core/string.h | 6 ++ src/core/uinteger.h | 7 +++ 9 files changed, 226 insertions(+), 2 deletions(-) diff --git a/src/core/attribute-helper.h b/src/core/attribute-helper.h index cf0c047e2..c9834f7e4 100644 --- a/src/core/attribute-helper.h +++ b/src/core/attribute-helper.h @@ -26,6 +26,35 @@ #include #include "fatal-error.h" +/** + * \defgroup AttributeHelper + * + * All these macros can be used to generate automatically the code + * for subclasses of AttributeValue, AttributeAccessor, and, AttributeChecker, + * which can be used to give attribute powers to a normal class. i.e., + * the user class can then effectively be made an attribute. + * + * There are two kinds of helper macros: + * 1) The simple macros. + * 2) The more complex macros. + * + * The simple macros are implemented in terms of the complex + * macros and should generally be prefered over the complex macros: + * - ATTRIBUTE_HELPER_HEADER_1, + * - ATTRIBUTE_HELPER_HEADER_2, and, + * - ATTRIBUTE_HELPER_CPP, + */ + +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro defines and generates the code for the implementation + * of the MakeXXXAccessor template functions. This macro is typically + * invoked in a class header to allow users of this class to view and + * use the template functions defined here. This macro is implemented + * through the helper templates functions ns3::MakeAccessorHelper<>. + */ #define ATTRIBUTE_ACCESSOR_DEFINE(type) \ template \ Ptr Make##type##Accessor (T1 a1) \ @@ -38,6 +67,13 @@ return MakeAccessorHelper (a1, a2); \ } +/** + * \ingroup AttributeHelper + * \param type the name of the class. + * + * This macro defines the class XXXValue associated to class XXX. + * This macro is typically invoked in a class header. + */ #define ATTRIBUTE_VALUE_DEFINE(type) \ class type##Value : public AttributeValue \ { \ @@ -55,14 +91,39 @@ type m_value; \ }; +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro defines the conversion operators for class XXX to and + * from instances of type Attribute. + * Typically invoked from xxx.h. + */ #define ATTRIBUTE_CONVERTER_DEFINE(type) \ type (Attribute value); \ operator Attribute () const; +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro defines the XXXChecker class and the associated + * MakeXXXChecker function. + * Typically invoked from xxx.h. + */ #define ATTRIBUTE_CHECKER_DEFINE(type) \ class type##Checker : public AttributeChecker {}; \ Ptr Make##type##Checker (void); \ +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro implements the XXXValue class (without the + * XXXValue::SerializeToString and XXXValue::DeserializeFromString + * methods). + * Typically invoked from xxx.cc. + */ #define ATTRIBUTE_VALUE_IMPLEMENT_NO_SERIALIZE(type) \ type##Value::type##Value () \ : m_value () {} \ @@ -92,6 +153,15 @@ return Attribute::Create (*this); \ } +/** + * \ingroup AttributeHelper + * \param type the name of the class. + * + * This macro implements the XXXValue class (including the + * XXXValue::SerializeToString and XXXValue::DeserializeFromString + * methods). + * Typically invoked from xxx.cc. + */ #define ATTRIBUTE_VALUE_IMPLEMENT(type) \ std::string \ type##Value::SerializeToString (Ptr checker) const { \ @@ -108,12 +178,26 @@ } \ ATTRIBUTE_VALUE_IMPLEMENT_NO_SERIALIZE (type) +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro implements the MakeXXXChecker function. + * Typically invoked from xxx.cc. + */ #define ATTRIBUTE_CHECKER_IMPLEMENT(type) \ Ptr Make##type##Checker (void) \ { \ return MakeSimpleAttributeChecker (); \ } \ +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro implements the conversion operators to and from + * instances of type Attribute. Typically invoked from xxx.cc. + */ #define ATTRIBUTE_CONVERTER_IMPLEMENT(type) \ type::type (Attribute value) \ { \ @@ -130,15 +214,35 @@ } +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro should be invoked from a public section of the class + * declaration. + */ #define ATTRIBUTE_HELPER_HEADER_1(type) \ ATTRIBUTE_CONVERTER_DEFINE (type) +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro should be invoked outside of the class + * declaration in its public header. + */ #define ATTRIBUTE_HELPER_HEADER_2(type) \ ATTRIBUTE_VALUE_DEFINE (type); \ ATTRIBUTE_ACCESSOR_DEFINE (type); \ ATTRIBUTE_CHECKER_DEFINE (type); -#define ATTRIBUTE_HELPER_CPP(type) \ +/** + * \ingroup AttributeHelper + * \param type the name of the class + * + * This macro should be invoked from the class implementation file. + */ +#define ATTRIBUTE_HELPER_CPP(type) \ ATTRIBUTE_CHECKER_IMPLEMENT (type); \ ATTRIBUTE_CONVERTER_IMPLEMENT (type); \ ATTRIBUTE_VALUE_IMPLEMENT (type); diff --git a/src/core/boolean.h b/src/core/boolean.h index 1f5f303d7..74885e089 100644 --- a/src/core/boolean.h +++ b/src/core/boolean.h @@ -25,6 +25,12 @@ namespace ns3 { +/** + * \brief Hold a bool native type + * + * This class can be used to hold bool variables + * which must go through the Attribute system. + */ class Boolean { public: diff --git a/src/core/command-line.h b/src/core/command-line.h index c20487dbc..0d6039d7f 100644 --- a/src/core/command-line.h +++ b/src/core/command-line.h @@ -26,16 +26,44 @@ namespace ns3 { +/** + * \brief parse command-line arguments + * + * Instances of this class can be used to parse command-line + * arguments: users can register new arguments with + * CommandLine::AddValue but the most important functionality + * provided by this class is that it can be used to set the + * 'initial value' of every attribute in the system with the + * --TypeIdName::AttributeName=value syntax and it can be used + * to set the value of every GlobalValue in the system with + * the --GlobalValueName=value syntax. + */ class CommandLine { public: ~CommandLine (); + /** + * \param name the name of the user-supplied argument + * \param help some help text used by --PrintHelp + * \param value a reference to the variable where the + * value parsed will be stored (if no value + * is parsed, this variable is not modified). + */ template void AddValue (const std::string &name, const std::string &help, T &value); + /** + * \param argc the 'argc' variable: number of arguments (including the + * main program name as first element). + * \param argv the 'argv' variable: a null-terminated array of strings, + * each of which identifies a command-line argument. + * + * Obviously, this method will parse the input command-line arguments and + * will attempt to handle them all. + */ void Parse (int &argc, char *argv[]) const; private: class Item diff --git a/src/core/double.h b/src/core/double.h index d7abf2c61..2d87aa46b 100644 --- a/src/core/double.h +++ b/src/core/double.h @@ -26,6 +26,12 @@ namespace ns3 { +/** + * \brief Hold an floating point type + * + * This class can be used to hold variables of floating point type + * such as 'double' or 'float'. The internal format is 'double'. + */ class Double { public: diff --git a/src/core/enum.h b/src/core/enum.h index f50d8421e..1e0aa78b2 100644 --- a/src/core/enum.h +++ b/src/core/enum.h @@ -26,6 +26,12 @@ namespace ns3 { +/** + * \brief hold variables of type 'enum' + * + * This class can be used to hold variables of any kind + * of enum. + */ class Enum : public AttributeValue { public: diff --git a/src/core/global-value.h b/src/core/global-value.h index 2d1a49dde..5e58f93e2 100644 --- a/src/core/global-value.h +++ b/src/core/global-value.h @@ -28,27 +28,81 @@ namespace ns3 { +/** + * \brief hold a so-called 'global value'. + * + * Instances of this class are expected to be allocated as static + * global variables and should be used to store configurable global state. + */ class GlobalValue { typedef std::vector Vector; public: typedef Vector::const_iterator Iterator; + /** + * \param name the name of this global value. + * \param help some help text which describes the purpose of this + * global value. + * \param initialValue the value to assign to this global value + * during construction. + * \param checker a pointer to an AttributeChecker which can verify + * that any user-supplied value to override the initial + * value matches the requested type constraints. + */ GlobalValue (std::string name, std::string help, Attribute initialValue, Ptr checker); + /** + * \returns the name of this GlobalValue. + */ std::string GetName (void) const; + /** + * \returns the help text of this GlobalValue. + */ std::string GetHelp (void) const; + /** + * \returns the current value of this GlobalValue. + */ Attribute GetValue (void) const; + /** + * \returns the checker associated to this GlobalValue. + */ Ptr GetChecker (void) const; - + /** + * \param value the new value to set in this GlobalValue. + */ bool SetValue (Attribute value); + /** + * \param name the name of the global value + * \param value the value to set in the requested global value. + * + * Iterate over the set of GlobalValues until a matching name is found + * and then set its value with GlobalValue::SetValue. + * + * This method cannot fail. It will crash if the input is not valid. + */ static void Bind (std::string name, Attribute value); + + /** + * \param name the name of the global value + * \param value the value to set in the requested global value. + * \returns true if the value could be set successfully, false otherwise. + * + * Iterate over the set of GlobalValues until a matching name is found + * and then set its value with GlobalValue::SetValue. + */ static bool BindFailSafe (std::string name, Attribute value); + /** + * \returns an iterator which represents a pointer to the first GlobalValue registered. + */ static Iterator Begin (void); + /** + * \returns an iterator which represents a pointer to the last GlobalValue registered. + */ static Iterator End (void); private: friend class GlobalValueTests; diff --git a/src/core/integer.h b/src/core/integer.h index 15c32ace3..dfd63ff94 100644 --- a/src/core/integer.h +++ b/src/core/integer.h @@ -26,6 +26,13 @@ namespace ns3 { +/** + * \brief Hold a signed integer type + * + * This class can be used to hold variables of signed integer + * type such as int8_t, int16_t, int32_t, int64_t, or, + * int, etc. + */ class Integer { public: diff --git a/src/core/string.h b/src/core/string.h index 77464cc0a..4d4c81075 100644 --- a/src/core/string.h +++ b/src/core/string.h @@ -6,6 +6,12 @@ namespace ns3 { +/** + * \brief hold variables of type string + * + * This class can be used to hold variables of type string, + * that is, either char * or std::string. + */ class String { public: diff --git a/src/core/uinteger.h b/src/core/uinteger.h index 5b120f7a2..84cd2f4e5 100644 --- a/src/core/uinteger.h +++ b/src/core/uinteger.h @@ -26,6 +26,13 @@ namespace ns3 { +/** + * \brief Hold an unsigned integer type + * + * This class can be used to hold variables of unsigned integer + * type such as uint8_t, uint16_t, uint32_t, uint64_t, or, + * unsigned int, etc. + */ class Uinteger { public: