diff --git a/doc/doxygen.conf b/doc/doxygen.conf index 66edea23e..3434995a4 100644 --- a/doc/doxygen.conf +++ b/doc/doxygen.conf @@ -1658,7 +1658,8 @@ PREDEFINED = \ NS3_LOG_ENABLE \ NS_LOG_COMPONENT_DEFINE()=1 \ NS_LOG_COMPONENT_DEFINE_MASK()=1 \ - NS_OBJECT_ENSURE_REGISTERED()=1 \ + NS_OBJECT_ENSURE_REGISTERED()=1 \ + # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then # this tag can be used to specify a list of macro names that should be expanded. @@ -1666,9 +1667,18 @@ PREDEFINED = \ # Use the PREDEFINED tag if you want to use a different macro definition that # overrules the definition found in the source code. -EXPAND_AS_DEFINED = ATTRIBUTE_VALUE_DEFINE \ +EXPAND_AS_DEFINED = ATTRIBUTE_ACCESSOR_DEFINE \ + ATTRIBUTE_CHECKER_DEFINE \ + ATTRIBUTE_CHECKER_IMPLEMENT \ + ATTRIBUTE_CHECKER_IMPLEMENT_WITH_NAME \ + ATTRIBUTE_CONVERTER_DEFINE \ + ATTRIBUTE_HELPER_CPP \ + ATTRIBUTE_HELPER_HEADER \ + ATTRIBUTE_VALUE_DEFINE \ ATTRIBUTE_VALUE_DEFINE_WITH_NAME \ - ATTRIBUTE_HELPER_HEADER_2 + ATTRIBUTE_VALUE_IMPLEMENT \ + ATTRIBUTE_VALUE_IMPLEMENT_WITH_NAME \ + # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then # doxygen's preprocessor will remove all references to function-like macros diff --git a/src/core/model/boolean.h b/src/core/model/boolean.h index b99c4dc32..ada957d56 100644 --- a/src/core/model/boolean.h +++ b/src/core/model/boolean.h @@ -25,26 +25,25 @@ namespace ns3 { -/** - * \ingroup attribute - * - * \brief Hold a bool native type - * - * \anchor bool - * - * This class can be used to hold bool variables - * which must go through the Attribute system. - */ class BooleanValue : public AttributeValue { public: BooleanValue (); + /** + * Construct from an explicit value. + * + * \param [in] value The boolean value to begin with. + */ BooleanValue (bool value); void Set (bool value); bool Get (void) const; template bool GetAccessor (T &v) const; + /** + * Functor returning the value. + * \returns The value. + */ operator bool () const; virtual Ptr Copy (void) const; @@ -61,6 +60,15 @@ bool BooleanValue::GetAccessor (T &v) const return true; } +/** + * Output streamer. + * + * The value is printed as "true" or "false". + * + * \param [in,out] os The stream. + * \param [in] value The BooleanValue to print. + * \returns The stream. + */ std::ostream & operator << (std::ostream &os, const BooleanValue &value); ATTRIBUTE_CHECKER_DEFINE (Boolean); diff --git a/src/core/model/callback.h b/src/core/model/callback.h index 7b039100c..8346c9ce8 100644 --- a/src/core/model/callback.h +++ b/src/core/model/callback.h @@ -102,11 +102,16 @@ namespace ns3 { * * Trait class to convert a pointer into a reference, * used by MemPtrCallBackImpl - * @{ */ template struct CallbackTraits; +/** + * \ingroup makecallbackmemptr + * + * Trait class to convert a pointer into a reference, + * used by MemPtrCallBackImpl + */ template struct CallbackTraits { @@ -119,7 +124,6 @@ struct CallbackTraits return *p; } }; -/**@}*/ /** * \ingroup callbackimpl @@ -962,6 +966,8 @@ protected: * Of course, it also does not use copy-destruction semantics * and relies on a reference list rather than autoPtr to hold * the pointer. + * + * \see attribute_Callback */ template MakeBoundCallback (R (*fnPtr)(TX1,TX2,TX3,T1,T2,T3 namespace ns3 { -/** - * \ingroup callback - * AttributeValue form of a Callback - */ class CallbackValue : public AttributeValue { public: @@ -1687,7 +1689,7 @@ public: CallbackValue (const CallbackBase &base); /** Destructor */ virtual ~CallbackValue (); - /** \param base the Callbackbase to use */ + /** \param base The CallbackBase to use */ void Set (CallbackBase base); /** * Give value my callback, if type compatible diff --git a/src/core/model/double.h b/src/core/model/double.h index b8c0a38e1..3ef34f818 100644 --- a/src/core/model/double.h +++ b/src/core/model/double.h @@ -27,26 +27,39 @@ namespace ns3 { +// Additional docs for class DoubleValue: /** - * \ingroup attribute - * - * \class ns3::DoubleValue - * \brief Hold a floating point type - * - * \anchor double * This class can be used to hold variables of floating point type * such as 'double' or 'float'. The internal format is 'double'. */ - ATTRIBUTE_VALUE_DEFINE_WITH_NAME (double, Double); ATTRIBUTE_ACCESSOR_DEFINE (Double); template Ptr MakeDoubleChecker (void); +/** + * Make a checker with a minimum value. + * + * The minimum value is included in the allowed range. + * + * \param [in] min The minimum value. + * \returns The AttributeChecker. + * \see AttributeChecker + */ template Ptr MakeDoubleChecker (double min); +/** + * Make a checker with a minimum and a maximum value. + * + * The minimum and maximum values are included in the allowed range. + * + * \param [in] min The minimum value. + * \param [in] max The maximum value. + * \returns The AttributeChecker. + * \see AttributeChecker + */ template Ptr MakeDoubleChecker (double min, double max); diff --git a/src/core/model/enum.cc b/src/core/model/enum.cc index 882f4e919..eb4c91199 100644 --- a/src/core/model/enum.cc +++ b/src/core/model/enum.cc @@ -27,26 +27,26 @@ namespace ns3 { NS_LOG_COMPONENT_DEFINE ("Enum"); EnumValue::EnumValue () - : m_v () + : m_value () { NS_LOG_FUNCTION (this); } -EnumValue::EnumValue (int v) - : m_v (v) +EnumValue::EnumValue (int value) + : m_value (value) { - NS_LOG_FUNCTION (this << v); + NS_LOG_FUNCTION (this << value); } void -EnumValue::Set (int v) +EnumValue::Set (int value) { - NS_LOG_FUNCTION (this << v); - m_v = v; + NS_LOG_FUNCTION (this << value); + m_value = value; } int EnumValue::Get (void) const { NS_LOG_FUNCTION (this); - return m_v; + return m_value; } Ptr EnumValue::Copy (void) const @@ -62,7 +62,7 @@ EnumValue::SerializeToString (Ptr checker) const NS_ASSERT (p != 0); for (EnumChecker::ValueSet::const_iterator i = p->m_valueSet.begin (); i != p->m_valueSet.end (); i++) { - if (i->first == m_v) + if (i->first == m_value) { return i->second; } @@ -82,7 +82,7 @@ EnumValue::DeserializeFromString (std::string value, Ptr { if (i->second == value) { - m_v = i->first; + m_value = i->first; return true; } } @@ -95,16 +95,16 @@ EnumChecker::EnumChecker () } void -EnumChecker::AddDefault (int v, std::string name) +EnumChecker::AddDefault (int value, std::string name) { - NS_LOG_FUNCTION (this << v << name); - m_valueSet.push_front (std::make_pair (v, name)); + NS_LOG_FUNCTION (this << value << name); + m_valueSet.push_front (std::make_pair (value, name)); } void -EnumChecker::Add (int v, std::string name) +EnumChecker::Add (int value, std::string name) { - NS_LOG_FUNCTION (this << v << name); - m_valueSet.push_back (std::make_pair (v, name)); + NS_LOG_FUNCTION (this << value << name); + m_valueSet.push_back (std::make_pair (value, name)); } bool EnumChecker::Check (const AttributeValue &value) const diff --git a/src/core/model/enum.h b/src/core/model/enum.h index d8e40c2f2..ae690e17e 100644 --- a/src/core/model/enum.h +++ b/src/core/model/enum.h @@ -26,36 +26,53 @@ namespace ns3 { +// Additional docs for class DoubleValue: /** - * \ingroup attribute - * - * \brief hold variables of type 'enum' + * Hold variables of type \c enum * * This class can be used to hold variables of any kind * of enum. + * + * This is often used with ObjectFactory and Config to bind + * the value of a particular enum to an Attribute or Config name. + * For example, + * \code + * Ptr model = CreateObjectWithAttributes ( + * "ErrorRate", DoubleValue (0.05), + * "ErrorUnit", EnumValue (RateErrorModel::ERROR_UNIT_PACKET)); + * + * Config::SetDefault ("ns3::RipNg::SplitHorizon", + * EnumValue (RipNg::NO_SPLIT_HORIZON)); + * \endcode */ class EnumValue : public AttributeValue { public: EnumValue (); - EnumValue (int v); - void Set (int v); + /** + * Construct from an explicit value. + * + * \param [in] value The value to begin with. + */ + EnumValue (int value); + void Set (int value); int Get (void) const; template - bool GetAccessor (T &v) const; + bool GetAccessor (T & value) const; virtual Ptr Copy (void) const; virtual std::string SerializeToString (Ptr checker) const; virtual bool DeserializeFromString (std::string value, Ptr checker); private: - int m_v; + int m_value; //!< The stored integer value. }; template -bool EnumValue::GetAccessor (T &v) const +bool +EnumValue::GetAccessor (T &value) const { - v = T (m_v); + value = T (m_value); return true; } @@ -64,8 +81,18 @@ class EnumChecker : public AttributeChecker public: EnumChecker (); - void AddDefault (int v, std::string name); - void Add (int v, std::string name); + /** + * Add a default value. + * \param [in] value The value. + * \param [in] name Then enum symbol name. + */ + void AddDefault (int value, std::string name); + /** + * Add a new value. + * \param [in] value The value. + * \param [in] name Then enum symbol name. + */ + void Add (int value, std::string name); virtual bool Check (const AttributeValue &value) const; virtual std::string GetValueTypeName (void) const; @@ -76,7 +103,9 @@ public: private: friend class EnumValue; + /** Type of container for storing Enum values and symbol names. */ typedef std::list > ValueSet; + /** The stored Enum values and symbol names. */ ValueSet m_valueSet; }; @@ -86,6 +115,62 @@ Ptr MakeEnumAccessor (T1 a1); template Ptr MakeEnumAccessor (T1 a1, T2 a2); +/** + * Make an EnumChecker pre-configured with a set of allowed + * values by name. + * + * Values are normally given as fully qualified enum symbols + * with matching names. For example, + * \c MakeEnumChecker (RipNg::SPLIT_HORIZON, "ns3::RipNg::SplitHorizon"); + * + * \see AttributeChecker + * + * \returns The AttributeChecker + * \param [in] v1 An enum value + * \param [in] n1 The corresponding name. + * \param [in] v2 A enum value + * \param [in] n2 The corresponding name. + * \param [in] v3 A enum value + * \param [in] n3 The corresponding name. + * \param [in] v4 A enum value + * \param [in] n4 The corresponding name. + * \param [in] v5 A enum value + * \param [in] n5 The corresponding name. + * \param [in] v6 A enum value + * \param [in] n6 The corresponding name. + * \param [in] v7 A enum value + * \param [in] n7 The corresponding name. + * \param [in] v8 A enum value + * \param [in] n8 The corresponding name. + * \param [in] v9 A enum value + * \param [in] n9 The corresponding name. + * \param [in] v10 An enum value + * \param [in] n10 The enum name. + * \param [in] v11 An enum value + * \param [in] n11 The corresponding name. + * \param [in] v12 A enum value + * \param [in] n12 The corresponding name. + * \param [in] v13 A enum value + * \param [in] n13 The corresponding name. + * \param [in] v14 A enum value + * \param [in] n14 The corresponding name. + * \param [in] v15 A enum value + * \param [in] n15 The corresponding name. + * \param [in] v16 A enum value + * \param [in] n16 The corresponding name. + * \param [in] v17 A enum value + * \param [in] n17 The corresponding name. + * \param [in] v18 A enum value + * \param [in] n18 The corresponding name. + * \param [in] v19 A enum value + * \param [in] n19 The corresponding name. + * \param [in] v20 An enum value + * \param [in] n20 The enum name. + * \param [in] v21 An enum value + * \param [in] n21 The corresponding name. + * \param [in] v22 A enum value + * \param [in] n22 The corresponding name. + */ Ptr MakeEnumChecker (int v1, std::string n1, int v2 = 0, std::string n2 = "", int v3 = 0, std::string n3 = "", diff --git a/src/core/model/integer.h b/src/core/model/integer.h index 98ddb63ec..6f2ee3309 100644 --- a/src/core/model/integer.h +++ b/src/core/model/integer.h @@ -27,30 +27,42 @@ namespace ns3 { +// Additional docs for class DoubleValue: /** - * \ingroup attribute - * \class ns3::IntegerValue - * \brief Hold a signed integer type - * - * \anchor int8_t - * \anchor int16_t - * \anchor int32_t - * \anchor int64_t + * 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. */ - ATTRIBUTE_VALUE_DEFINE_WITH_NAME (int64_t, Integer); ATTRIBUTE_ACCESSOR_DEFINE (Integer); template Ptr MakeIntegerChecker (void); +/** + * Make a checker with a minimum value. + * + * The minimum value is included in the allowed range. + * + * \param [in] min The minimum value. + * \returns The AttributeChecker. + * \see AttributeChecker + */ template Ptr MakeIntegerChecker (int64_t min); +/** + * Make a checker with a minimum and a maximum value. + * + * The minimum and maximum values are included in the allowed range. + * + * \param [in] min The minimum value. + * \param [in] max The maximum value. + * \returns The AttributeChecker. + * \see AttributeChecker + */ template Ptr MakeIntegerChecker (int64_t min, int64_t max); diff --git a/src/core/model/nstime.h b/src/core/model/nstime.h index 33768a3d3..1af8b4485 100644 --- a/src/core/model/nstime.h +++ b/src/core/model/nstime.h @@ -91,6 +91,8 @@ class TimeWithUnit; * resolution. Therefore the maximum duration of your simulation, * if you use picoseconds, is 2^64 ps = 2^24 s = 7 months, whereas, * had you used nanoseconds, you could have run for 584 years. + * + * \see attribute_Time */ class Time { @@ -913,24 +915,14 @@ inline Time TimeStep (uint64_t ts) return Time (ts); } -/** - * \ingroup time - * \class ns3::TimeValue - * \brief Attribute for objects of type ns3::Time - */ ATTRIBUTE_VALUE_DEFINE (Time); - -/** - * Attribute accessor function for Time - * @{ - */ ATTRIBUTE_ACCESSOR_DEFINE (Time); -/**@}*/ /** - * \ingroup time + * \ingroup attribute_Time * \brief Helper to make a Time checker with bounded range. - * Both limits are inclusive + * + * The minimum and maximum values are included in the allowed range. * * \param [in] min Minimum allowed value. * \param [in] max Maximum allowed value. @@ -938,12 +930,6 @@ ATTRIBUTE_ACCESSOR_DEFINE (Time); */ Ptr MakeTimeChecker (const Time min, const Time max); -/** - * \ingroup time - * \brief Helper to make an unbounded Time checker. - * - * \return the AttributeChecker - */ inline Ptr MakeTimeChecker (void) { @@ -951,9 +937,11 @@ Ptr MakeTimeChecker (void) } /** - * \ingroup time + * \ingroup attribute_Time * \brief Helper to make a Time checker with a lower bound. * + * The minimum value is included in the allowed range. + * * \param [in] min Minimum allowed value. * \return the AttributeChecker */ diff --git a/src/core/model/object-base.h b/src/core/model/object-base.h index 816f65f1d..4a152fbdb 100644 --- a/src/core/model/object-base.h +++ b/src/core/model/object-base.h @@ -165,6 +165,16 @@ protected: void ConstructSelf (const AttributeConstructionList &attributes); private: + /** + * Attempt to set the value referenced by the accessor \p spec + * to a valid value according to the \c checker, based on \p value. + * + * \param [in] spec The accessor for the storage location. + * \param [in] checker The checker to use in validating the value. + * \param [in] value The value to attempt to store. + * \returns true if the \c value could be validated by the \p checker + * and written to the storage location. + */ bool DoSet (Ptr spec, Ptr checker, const AttributeValue &value); diff --git a/src/core/model/object-factory.h b/src/core/model/object-factory.h index f70eba425..4a055f8ba 100644 --- a/src/core/model/object-factory.h +++ b/src/core/model/object-factory.h @@ -35,6 +35,8 @@ class AttributeValue; * * This class can also hold a set of attributes to set * automatically during the object construction. + * + * \see attribute_ObjectFactory */ class ObjectFactory { @@ -129,13 +131,6 @@ CreateObjectWithAttributes (std::string n1 = "", const AttributeValue & v1 = Emp std::string n9 = "", const AttributeValue & v9 = EmptyAttributeValue ()); - - -/** - * \class ns3::ObjectFactoryValue - * \brief hold objects of type ns3::ObjectFactory - */ - ATTRIBUTE_HELPER_HEADER (ObjectFactory); } // namespace ns3 diff --git a/src/core/model/object-map.h b/src/core/model/object-map.h index 24524c7d2..53043d3a3 100644 --- a/src/core/model/object-map.h +++ b/src/core/model/object-map.h @@ -27,25 +27,48 @@ namespace ns3 { +/** + * \ingroup attribute_ObjectMap + * ObjectVectorMap is an alias for ObjectPtrContainerValue + */ typedef ObjectPtrContainerValue ObjectMapValue; +/** + * \ingroup attribute_ObjectMap + * MakeAccessorHelper implementation for ObjectVector. + * \copydetails ns3::DoMakeAccessorHelperOne(U T::*) + */ template Ptr -MakeObjectMapAccessor (U T::*memberContainer); +MakeObjectMapAccessor (U T::*memberVariable); +// Documentation generated by print-introspected-doxygen.cc template Ptr MakeObjectMapChecker (void); +/** + * \ingroup attribute_ObjectMap + * \copydoc ns3::MakeObjectPtrContainerAccessor() + */ template Ptr MakeObjectMapAccessor (Ptr (T::*get)(INDEX) const, INDEX (T::*getN)(void) const); +/** + * \ingroup attribute_ObjectMap + * \copydoc ns3::MakeObjectPtrContainerAccessor() + */ template Ptr MakeObjectMapAccessor (INDEX (T::*getN)(void) const, Ptr (T::*get)(INDEX) const); + +/*************************************************************** + * The implementation of the above functions. + ***************************************************************/ + template Ptr MakeObjectMapAccessor (U T::*memberVector) diff --git a/src/core/model/object-ptr-container.h b/src/core/model/object-ptr-container.h index 215a4056a..6867ead99 100644 --- a/src/core/model/object-ptr-container.h +++ b/src/core/model/object-ptr-container.h @@ -38,8 +38,10 @@ namespace ns3 { class ObjectPtrContainerValue : public AttributeValue { public: + /** Iterator type for traversing this container. */ typedef std::map >::const_iterator Iterator; + /** Default constructor. */ ObjectPtrContainerValue (); /** @@ -66,15 +68,45 @@ public: private: friend class ObjectPtrContainerAccessor; + /** The container implementation. */ std::map > m_objects; }; - +/** + * \ingroup attribute_ObjectPtrContainer + * Create an AttributeAccessor using a container class indexed get method. + * + * The two versions of this function differ only in argument order. + * + * \tparam T The container class type. + * \tparam U The type of object the get method returns. + * \tparam INDEX The type of the index variable. + * \param [in] get The class method to get a specific instance + * from the container. + * \param [in] getN The class method to return the number of objects + * in the container. + * \return The AttributeAccessor. + */ template Ptr MakeObjectPtrContainerAccessor (Ptr (T::*get)(INDEX) const, INDEX (T::*getN)(void) const); +/** + * \ingroup attribute_ObjectPtrContainer + * Create an AttributeAccessor using a container class indexed get method. + * + * The two versions of this function differ only in argument order. + * + * \tparam T The container class type. + * \tparam U The type of object the get method returns. + * \tparam INDEX The type of the index variable. + * \param [in] get The class method to get a specific instance + * from the container. + * \param [in] getN The class method to return the number of objects + * in the container. + * \return The AttributeAccessor. + */ template Ptr MakeObjectPtrContainerAccessor (INDEX (T::*getN)(void) const, @@ -83,6 +115,10 @@ MakeObjectPtrContainerAccessor (INDEX (T::*getN)(void) const, class ObjectPtrContainerChecker : public AttributeChecker { public: + /** + * Get the TypeId of the container class type. + * \returns The class TypeId. + */ virtual TypeId GetItemTypeId (void) const = 0; }; @@ -91,12 +127,18 @@ Ptr MakeObjectPtrContainerChecker (void); } // namespace ns3 + +/*************************************************************** + * The implementation of the above functions. + ***************************************************************/ + namespace ns3 { namespace internal { +/** ObjectPtrContainerChecker implementation class. */ template -class AnObjectPtrContainerChecker : public ObjectPtrContainerChecker +class ObjectPtrContainerChecker : public ns3::ObjectPtrContainerChecker { public: virtual TypeId GetItemTypeId (void) const { @@ -131,7 +173,8 @@ public: } // namespace internal - + +/** AttributeAccessor implementation for ObjectPtrContainerValue. */ class ObjectPtrContainerAccessor : public AttributeAccessor { public: @@ -140,7 +183,22 @@ public: virtual bool HasGetter (void) const; virtual bool HasSetter (void) const; private: + /** + * Get the number of instances in the container. + * + * \param [in] object The container object. + * \param [out] n The number of instances in the container. + * \returns true if the value could be obtained successfully. + */ virtual bool DoGetN (const ObjectBase *object, uint32_t *n) const = 0; + /** + * Get an instance from the container, identified by index. + * + * \param [in] object The container object. + * \param [in] i The desired instance index. + * \param [out] index The index retrieved. + * \returns The index requested. + */ virtual Ptr DoGet (const ObjectBase *object, uint32_t i, uint32_t *index) const = 0; }; @@ -184,7 +242,7 @@ MakeObjectPtrContainerAccessor (INDEX (T::*getN)(void) const, template Ptr MakeObjectPtrContainerChecker (void) { - return Create > (); + return Create > (); } diff --git a/src/core/model/object-vector.h b/src/core/model/object-vector.h index 969e2228a..92eb058e8 100644 --- a/src/core/model/object-vector.h +++ b/src/core/model/object-vector.h @@ -27,25 +27,49 @@ namespace ns3 { +/** + * \ingroup attribute_ObjectVector + * ObjectVectorValue is an alias for ObjectPtrContainerValue + */ typedef ObjectPtrContainerValue ObjectVectorValue; +/** + * \ingroup attribute_ObjectVector + * MakeAccessorHelper implementation for ObjectVector. + * \copydetails ns3::DoMakeAccessorHelperOne(U T::*) + */ template Ptr -MakeObjectVectorAccessor (U T::*memberContainer); +MakeObjectVectorAccessor (U T::*memberVariable); +// Documentation generated by print-introspected-doxygen.cc template -Ptr MakeObjectVectorChecker (void); +Ptr +MakeObjectVectorChecker (void); +/** + * \ingroup attribute_ObjectVector + * \copydoc ns3::MakeObjectPtrContainerAccessor() + */ template Ptr MakeObjectVectorAccessor (Ptr (T::*get)(INDEX) const, INDEX (T::*getN)(void) const); +/** + * \ingroup attribute_ObjectVector + * \copydoc ns3::MakeObjectPtrContainerAccessor() + */ template Ptr MakeObjectVectorAccessor (INDEX (T::*getN)(void) const, Ptr (T::*get)(INDEX) const); + +/*************************************************************** + * The implementation of the above functions. + ***************************************************************/ + template Ptr MakeObjectVectorAccessor (U T::*memberVector) diff --git a/src/core/model/pointer.h b/src/core/model/pointer.h index 04657f2d0..1badad152 100644 --- a/src/core/model/pointer.h +++ b/src/core/model/pointer.h @@ -25,36 +25,55 @@ namespace ns3 { -/** - * \ingroup attribute - * - * \brief hold objects of type Ptr - */ +// Additional docs for class PointerValue: +/** Hold objects of type Ptr. */ class PointerValue : public AttributeValue { public: PointerValue (); - + + /** + * Construct this PointerValue by referencing an explicit Object. + * + * \param [in] object The object to begin with. + */ PointerValue (Ptr object); + /** + * Set the value from by reference an Object. + * + * \param [in] object The object to reference. + */ void SetObject (Ptr object); + /** + * Get the Object referenced by the PointerValue. + * \returns The Object. + */ Ptr GetObject (void) const; + /** + * Construct this PointerValue by referencing an explicit Object. + * + * \tparam T (implicit) The type of the object. + * \param [in] object The object to begin with. + */ template - PointerValue (const Ptr &object); + PointerValue (const Ptr & object); + /** Cast to an Object of type \c T. */ template - void Set (const Ptr &object); + operator Ptr () const; + + // Documentation generated by print-introspected-doxygen.cc + template + void Set (const Ptr & value); template Ptr Get (void) const; template - bool GetAccessor (Ptr &v) const; - - template - operator Ptr () const; + bool GetAccessor (Ptr &value) const; virtual Ptr Copy (void) const; virtual std::string SerializeToString (Ptr checker) const; @@ -68,6 +87,11 @@ private: class PointerChecker : public AttributeChecker { public: + + /** + * Get the TypeId of the base type. + * \returns The base TypeId. + */ virtual TypeId GetPointeeTypeId (void) const = 0; }; template @@ -80,8 +104,9 @@ namespace ns3 { namespace internal { +/** PointerChecker implementation. */ template -class APointerChecker : public PointerChecker +class PointerChecker : public ns3::PointerChecker { virtual bool Check (const AttributeValue &val) const { const PointerValue *value = dynamic_cast (&val); @@ -177,7 +202,7 @@ template Ptr MakePointerChecker (void) { - return Create > (); + return Create > (); } diff --git a/src/core/model/string.h b/src/core/model/string.h index ef11f1156..ffc1d8c10 100644 --- a/src/core/model/string.h +++ b/src/core/model/string.h @@ -25,11 +25,9 @@ namespace ns3 { +// Additional docs for class DoubleValue: /** - * \ingroup attribute - * - * \class ns3::StringValue - * \brief hold variables of type string + * Hold variables of type string * * This class can be used to hold variables of type string, * that is, either char * or std::string. diff --git a/src/core/model/type-id.h b/src/core/model/type-id.h index d48699290..ea851c55b 100644 --- a/src/core/model/type-id.h +++ b/src/core/model/type-id.h @@ -42,10 +42,11 @@ class ObjectBase; * - the set of accessible constructors in the subclass * - the set of 'attributes' accessible in the subclass * + * \see attribute_TypeId + * * \internal * See the discussion in IidManager about hash chaining of TypeId's. - * - */ + */ class TypeId { public: diff --git a/src/core/model/uinteger.h b/src/core/model/uinteger.h index 881f103bf..7e0c29e7b 100644 --- a/src/core/model/uinteger.h +++ b/src/core/model/uinteger.h @@ -27,16 +27,9 @@ namespace ns3 { +// Additional docs for class DoubleValue: /** - * \ingroup attribute - * - * \class ns3::UintegerValue - * \brief Hold an unsigned integer type - * - * \anchor uint8_t - * \anchor uint16_t - * \anchor uint32_t - * \anchor uint64_t + * 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, @@ -49,9 +42,28 @@ ATTRIBUTE_ACCESSOR_DEFINE (Uinteger); template Ptr MakeUintegerChecker (void); +/** + * Make a checker with a minimum value. + * + * The minimum value is included in the allowed range. + * + * \param [in] min The minimum value. + * \returns The AttributeChecker. + * \see AttributeChecker + */ template Ptr MakeUintegerChecker (uint64_t min); +/** + * Make a checker with a minimum and a maximum value. + * + * The minimum and maximum values are included in the allowed range. + * + * \param [in] min The minimum value. + * \param [in] max The maximum value. + * \returns The AttributeChecker. + * \see AttributeChecker + */ template Ptr MakeUintegerChecker (uint64_t min, uint64_t max); diff --git a/src/core/model/vector.h b/src/core/model/vector.h index eaf081916..eaa0b92e7 100644 --- a/src/core/model/vector.h +++ b/src/core/model/vector.h @@ -27,6 +27,7 @@ namespace ns3 { /** * \brief a 3d vector + * \see attribute_Vector3D */ class Vector3D { @@ -55,10 +56,15 @@ public: * z coordinate of vector */ double z; + + friend double CalculateDistance (const Vector3D &a, const Vector3D &b); + friend std::ostream &operator << (std::ostream &os, const Vector3D &vector); + friend std::istream &operator >> (std::istream &is, Vector3D &vector); }; /** - * \brief a 3d vector + * \brief a 2d vector + * \see attribute_Vector2D */ class Vector2D { @@ -82,6 +88,10 @@ public: * y coordinate of vector */ double y; + + friend double CalculateDistance (const Vector2D &a, const Vector2D &b); + friend std::ostream &operator << (std::ostream &os, const Vector2D &vector); + friend std::istream &operator >> (std::istream &is, Vector2D &vector); }; /** @@ -90,7 +100,6 @@ public: * \returns the cartesian distance between a and b. */ double CalculateDistance (const Vector3D &a, const Vector3D &b); - /** * \param a one point * \param b another point @@ -98,28 +107,91 @@ double CalculateDistance (const Vector3D &a, const Vector3D &b); */ double CalculateDistance (const Vector2D &a, const Vector2D &b); -/** - * \class ns3::Vector3DValue - * \brief hold objects of type ns3::Vector3D - */ -/** - * \class ns3::Vector2DValue - * \brief hold objects of type ns3::Vector2D - */ ATTRIBUTE_HELPER_HEADER (Vector3D); ATTRIBUTE_HELPER_HEADER (Vector2D); +/** + * Output streamer. + * + * Vectors are written as "x:y:z". + * + * \param [in,out] os The stream. + * \param [in] vector The vector to stream + * \return The stream. + */ std::ostream &operator << (std::ostream &os, const Vector3D &vector); -std::istream &operator >> (std::istream &is, Vector3D &vector); +/** + * Output streamer. + * + * Vectors are written as "x:y". + * + * \param [in,out] os The stream. + * \param [in] vector The vector to stream + * \return The stream. + */ std::ostream &operator << (std::ostream &os, const Vector2D &vector); + +/** + * Input streamer. + * + * Vectors are expected to be in the form "x:y:z". + * + * \param [in,out] is The stream. + * \param [in] vector The vector. + * \returns The stream. + */ +std::istream &operator >> (std::istream &is, Vector3D &vector); +/** + * Input streamer. + * + * Vectors are expected to be in the form "x:y". + * + * \param [in,out] is The stream. + * \param [in] vector The vector. + * \returns The stream. + */ std::istream &operator >> (std::istream &is, Vector2D &vector); -// for compatibility with mobility models + +/** + * \relates Vector3D + * Vector alias typedef for compatibility with mobility models + */ typedef Vector3D Vector; +/** + * \ingroup attribute_Vector3D + * Vector alias typedef for compatibility with mobility models + */ typedef Vector3DValue VectorValue; +/** + * \ingroup attribute_Vector3D + * Vector alias typedef for compatibility with mobility models + */ typedef Vector3DChecker VectorChecker; + + +// Document these by hand so they go in group attribute_Vector3D +/** + * \ingroup attribute_Vector3D + * \fn ns3::Ptr ns3::MakeVectorAccessor (T1 a1) + * \copydoc ns3::MakeAccessorHelper(T1) + * \see AttributeAccessor + */ +/** + * \ingroup attribute_Vector3D + * \fn ns3::Ptr ns3::MakeVectorAccessor (T1 a1, T2 a2) + * \copydoc ns3::MakeAccessorHelper(T1,T2) + * \see AttributeAccessor + */ + ATTRIBUTE_ACCESSOR_DEFINE (Vector); -Ptr MakeVectorChecker (void); + +/** + * \ingroup attribute_Vector3D + * \returns The AttributeChecker. + * \see AttributeChecker + */ +Ptr MakeVectorChecker (void); } // namespace ns3 diff --git a/src/core/test/attribute-test-suite.cc b/src/core/test/attribute-test-suite.cc index 8ce027f70..8510f5405 100644 --- a/src/core/test/attribute-test-suite.cc +++ b/src/core/test/attribute-test-suite.cc @@ -37,6 +37,10 @@ using namespace ns3; +/** + * Test class for TracedValue callbacks. + * \see attribute_ValueClassTest + */ class ValueClassTest { public: diff --git a/src/mesh/model/dot11s/ie-dot11s-id.h b/src/mesh/model/dot11s/ie-dot11s-id.h index 9bef2509d..d9db9174a 100644 --- a/src/mesh/model/dot11s/ie-dot11s-id.h +++ b/src/mesh/model/dot11s/ie-dot11s-id.h @@ -29,7 +29,7 @@ namespace ns3 { namespace dot11s { /** * \brief a IEEE 802.11s Mesh ID 7.3.287 of 802.11s draft 3.0 - * + * \see attribute_IeMeshId */ class IeMeshId : public WifiInformationElement { diff --git a/src/mobility/model/box.h b/src/mobility/model/box.h index dc9c1c682..ea62c1c0d 100644 --- a/src/mobility/model/box.h +++ b/src/mobility/model/box.h @@ -29,6 +29,7 @@ namespace ns3 { /** * \ingroup mobility * \brief a 3d box + * \see attribute_Box */ class Box { @@ -102,11 +103,6 @@ public: std::ostream &operator << (std::ostream &os, const Box &box); std::istream &operator >> (std::istream &is, Box &box); -/** - * \class ns3::BoxValue - * \brief hold objects of type ns3::Box - */ - ATTRIBUTE_HELPER_HEADER (Box); } // namespace ns3 diff --git a/src/mobility/model/rectangle.h b/src/mobility/model/rectangle.h index ece8f2492..c46751927 100644 --- a/src/mobility/model/rectangle.h +++ b/src/mobility/model/rectangle.h @@ -29,6 +29,7 @@ namespace ns3 { /** * \ingroup mobility * \brief a 2d rectangle + * \see attribute_Rectangle */ class Rectangle { diff --git a/src/mobility/model/waypoint.h b/src/mobility/model/waypoint.h index 96d7d4fef..25b57525c 100644 --- a/src/mobility/model/waypoint.h +++ b/src/mobility/model/waypoint.h @@ -30,6 +30,7 @@ namespace ns3 { /** * \ingroup mobility * \brief a (time, location) pair. + * \see attribute_Waypoint */ class Waypoint { diff --git a/src/network/model/address.h b/src/network/model/address.h index 48e109e58..70a51f9ab 100644 --- a/src/network/model/address.h +++ b/src/network/model/address.h @@ -32,6 +32,8 @@ namespace ns3 { /** * \ingroup network * \defgroup address Address + * + * Network Address abstractions, including MAC, IPv4 and IPv6. */ /** * \ingroup address @@ -82,6 +84,8 @@ namespace ns3 { * return type; * } * \endcode + * + * \see attribute_Address */ class Address { @@ -271,12 +275,7 @@ private: uint8_t m_data[MAX_SIZE]; //!< The address value }; -/** - * \class ns3::AddressValue - * \brief hold objects of type ns3::Address - */ - -ATTRIBUTE_HELPER_HEADER (Address); //!< Macro to make help make class an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (Address); bool operator == (const Address &a, const Address &b); bool operator != (const Address &a, const Address &b); diff --git a/src/network/utils/data-rate.h b/src/network/utils/data-rate.h index 00313d3d2..e19345a97 100644 --- a/src/network/utils/data-rate.h +++ b/src/network/utils/data-rate.h @@ -41,32 +41,48 @@ namespace ns3 { * Allows for natural and familiar use of data rates. Allows construction * from strings, natural multiplication e.g.: * \code - * DataRate x("56kbps"); - * double nBits = x*ns3::Seconds(19.2); - * uint32_t nBytes = 20; - * double txtime = x.CalclulateTxTime(nBytes); + * DataRate x("56kbps"); + * double nBits = x*ns3::Seconds(19.2); + * uint32_t nBytes = 20; + * double txtime = x.CalclulateTxTime(nBytes); * \endcode - * This class also supports the regular comparison operators <, >, <=, >=, ==, - * and != + * This class also supports the regular comparison operators \c <, \c >, + * \c <=, \c >=, \c ==, and \c != * - * Conventions used: - * "b" stands for bits, "B" for bytes (8 bits) \n - * "k" stands for 1000, "K" also stands for 1000, "Ki" stands for 1024 \n - * "M" stand for 1000000, "Mib" stands for 1024 kibibits, or 1048576 bits \n - * "G" stand for 10^9, "Gib" stands for 1024 mebibits \n - * whitespace is allowed but not required between the numeric value and units + * Data rate specifiers consist of + * * A numeric value, + * * An optional multiplier prefix and + * * A unit. + * + * Whitespace is allowed but not required between the numeric value and + * multipler or unit. + * + * Supported multiplier prefixes: + * + * | Prefix | Value | + * | :------- | ----------: | + * | "k", "K" | 1000 | + * | "Ki" | 1024 | + * | "M" | 1000000 | + * | "Mi" | 1024 Ki | + * | "G" | 10^9 | + * | "Gi " | 1024 Mi | * * Supported unit strings: - * bps, b/s, Bps, B/s \n - * kbps, kb/s, Kbps, Kb/s, kBps, kB/s, KBps, KB/s, Kib/s, KiB/s \n - * Mbps, Mb/s, MBps, MB/s, Mib/s, MiB/s \n - * Gbps, Gb/s, GBps, GB/s, Gib/s, GiB/s \n - * + * + * | Symbol | Meaning | + * | :------- | :---------- | + * | "b" | bits | + * | "B" | 8-bit bytes | + * | "s", "/s"| per second | + * * Examples: - * "56kbps" = 56,000 bits/s \n - * "128 kb/s" = 128,000 bits/s \n - * "8Kib/s" = 1 KiB/s = 8192 bits/s \n - * "1kB/s" = 8000 bits/s + * * "56kbps" = 56,000 bits/s + * * "128 kb/s" = 128,000 bits/s + * * "8Kib/s" = 1 KiB/s = 8192 bits/s + * * "1kB/s" = 8000 bits/s + * + * \see attribute_DataRate */ class DataRate { @@ -200,13 +216,7 @@ std::ostream &operator << (std::ostream &os, const DataRate &rate); */ std::istream &operator >> (std::istream &is, DataRate &rate); -/** - * \class ns3::DataRateValue - * \brief hold objects of type ns3::DataRate - */ - - -ATTRIBUTE_HELPER_HEADER (DataRate); //!< Macro to make help make data-rate an ns-3 attribute +ATTRIBUTE_HELPER_HEADER (DataRate); /** diff --git a/src/network/utils/ipv4-address.h b/src/network/utils/ipv4-address.h index 4e3c38794..c61450579 100644 --- a/src/network/utils/ipv4-address.h +++ b/src/network/utils/ipv4-address.h @@ -34,6 +34,8 @@ class Ipv4Mask; * \ingroup address * * \brief Ipv4 addresses are stored in host order in this class. + * + * \see attribute_Ipv4Address */ class Ipv4Address { public: @@ -218,6 +220,8 @@ private: * The constructor takes arguments according to a few formats. * Ipv4Mask ("255.255.255.255"), Ipv4Mask ("/32"), and Ipv4Mask (0xffffffff) * are all equivalent. + * + * \see attribute_Ipv4Mask */ class Ipv4Mask { public: diff --git a/src/network/utils/ipv6-address.h b/src/network/utils/ipv6-address.h index 0c5cc88a3..de5b79f70 100644 --- a/src/network/utils/ipv6-address.h +++ b/src/network/utils/ipv6-address.h @@ -42,6 +42,7 @@ class Mac64Address; * \class Ipv6Address * \brief Describes an IPv6 address. * \see Ipv6Prefix + * \see attribute_Ipv6Address */ class Ipv6Address { @@ -383,6 +384,7 @@ private: * \class Ipv6Prefix * \brief Describes an IPv6 prefix. It is just a bitmask like Ipv4Mask. * \see Ipv6Address + * \see attribute_Ipv6Prefix */ class Ipv6Prefix { diff --git a/src/network/utils/mac16-address.h b/src/network/utils/mac16-address.h index f2bd42d03..456aa439a 100644 --- a/src/network/utils/mac16-address.h +++ b/src/network/utils/mac16-address.h @@ -35,6 +35,8 @@ class Address; * \ingroup address * * This class can contain 16 bit addresses. + * + * \see attribute_Mac16Address */ class Mac16Address { diff --git a/src/network/utils/mac48-address.h b/src/network/utils/mac48-address.h index 989f66935..121a3b5e3 100644 --- a/src/network/utils/mac48-address.h +++ b/src/network/utils/mac48-address.h @@ -37,6 +37,8 @@ class Address; * \brief an EUI-48 address * * This class can contain 48 bit IEEE addresses. + * + * \see attribute_Mac48Address */ class Mac48Address { diff --git a/src/network/utils/mac64-address.h b/src/network/utils/mac64-address.h index bcf400601..f6d01eadc 100644 --- a/src/network/utils/mac64-address.h +++ b/src/network/utils/mac64-address.h @@ -37,6 +37,8 @@ class Address; * \brief an EUI-64 address * * This class can contain 64 bit IEEE addresses. + * + * \see attribute_Mac64Address */ class Mac64Address { diff --git a/src/uan/model/uan-tx-mode.h b/src/uan/model/uan-tx-mode.h index 3651d68d8..1255364db 100644 --- a/src/uan/model/uan-tx-mode.h +++ b/src/uan/model/uan-tx-mode.h @@ -251,6 +251,8 @@ private: * \ingroup uan * * Container for UanTxModes. + * + * \see attribute_UanModesList */ class UanModesList { diff --git a/src/wave/model/vendor-specific-action.h b/src/wave/model/vendor-specific-action.h index c6f25e872..3aa5a934c 100644 --- a/src/wave/model/vendor-specific-action.h +++ b/src/wave/model/vendor-specific-action.h @@ -45,6 +45,8 @@ class VendorSpecificContentManager; * Normally the value is assigned by IEEE and the length of field is * either 24 bits or 36 bits. * For more, see IEEE802.11p-2010 section 7.3.1.31 and 7.4.5 + * + * \see attribute_OrganizationIdentifier */ class OrganizationIdentifier { diff --git a/src/wifi/model/ht-capabilities.h b/src/wifi/model/ht-capabilities.h index a77d149aa..43d6d7b14 100644 --- a/src/wifi/model/ht-capabilities.h +++ b/src/wifi/model/ht-capabilities.h @@ -38,6 +38,8 @@ namespace ns3 { * \ingroup wifi * * This class knows how to serialise and deserialise the Ht Capabilities Information Element + * + * \see attribute_HtCapabilities */ class HtCapabilities: public WifiInformationElement { diff --git a/src/wifi/model/ssid.h b/src/wifi/model/ssid.h index a20d71f1c..44329f0ad 100644 --- a/src/wifi/model/ssid.h +++ b/src/wifi/model/ssid.h @@ -31,6 +31,8 @@ namespace ns3 { * \ingroup wifi * * The IEEE 802.11 SSID Information Element + * + * \see attribute_Ssid */ class Ssid : public WifiInformationElement { diff --git a/src/wifi/model/wifi-mode.h b/src/wifi/model/wifi-mode.h index 5ca910ca4..6910561b5 100644 --- a/src/wifi/model/wifi-mode.h +++ b/src/wifi/model/wifi-mode.h @@ -87,6 +87,8 @@ enum WifiCodeRate * to lookup in a global array the characteristics of the * associated transmission mode. It is thus extremely cheap to * keep a WifiMode variable around. + * + * \see attribute_WifiMode */ class WifiMode { diff --git a/utils/print-introspected-doxygen.cc b/utils/print-introspected-doxygen.cc index 4532825ea..80c7ecf3c 100644 --- a/utils/print-introspected-doxygen.cc +++ b/utils/print-introspected-doxygen.cc @@ -41,18 +41,23 @@ NS_LOG_COMPONENT_DEFINE ("PrintIntrospectedDoxygen"); namespace { std::string anchor; ///< hyperlink anchor + std::string argument; ///< function argument std::string boldStart; ///< start of bold span std::string boldStop; ///< end of bold span std::string breakBoth; ///< linebreak std::string breakHtmlOnly; ///< linebreak for html output only std::string breakTextOnly; ///< linebreak for text output only std::string brief; ///< brief tag + std::string classStart; ///< start of a class + std::string classStop; ///< end of a class + std::string codeWord; ///< format next word as source code std::string commentStart; ///< start of code comment std::string commentStop; ///< end of code comment + std::string copyDoc; ///< copy (or refer) to docs elsewhere std::string flagSpanStart; ///< start of Attribute flag value std::string flagSpanStop; ///< end of Attribute flag value - std::string functionStart; ///< start of a class/function - std::string functionStop; ///< end of a class/function + std::string functionStart; ///< start of a method/function + std::string functionStop; ///< end of a method/function std::string headingStart; ///< start of section heading (h3) std::string headingStop; ///< end of section heading (h3) std::string indentHtmlOnly; ///< small indent @@ -62,9 +67,12 @@ namespace std::string listStop; ///< end unordered list std::string page; ///< start a separate page std::string reference; ///< reference tag + std::string returns; ///< the return value std::string sectionStart; ///< start of a section or group + std::string seeAlso; ///< Reference to other docs std::string subSectionStart; ///< start a new subsection std::string temporaryCharacter; ///< "%" placeholder + std::string variable; ///< variable or class member } // anonymous namespace @@ -72,7 +80,7 @@ namespace /** * Initialize the markup strings, for either doxygen or text. * - * \param [in] outpuText true for text output, false for doxygen output. + * \param [in] outputText true for text output, false for doxygen output. */ void SetMarkup (bool outputText) @@ -81,14 +89,19 @@ SetMarkup (bool outputText) if (outputText) { anchor = ""; + argument = " Arg: "; boldStart = ""; boldStop = ""; breakBoth = "\n"; breakHtmlOnly = ""; breakTextOnly = "\n"; brief = ""; + classStart = ""; + classStop = "\n\n"; + codeWord = " "; commentStart = "===============================================================\n"; commentStop = ""; + copyDoc = " See: "; flagSpanStart = ""; flagSpanStop = ""; functionStart = ""; @@ -101,25 +114,33 @@ SetMarkup (bool outputText) listStop = ""; listLineStart = " * "; listLineStop = ""; - reference = ""; + reference = " "; + returns = " Returns: "; sectionStart = "Section "; + seeAlso = " See: "; subSectionStart = "Subsection "; temporaryCharacter = ""; + variable = "Variable: "; } else { anchor = "\\anchor "; + argument = "\\param "; boldStart = ""; boldStop = ""; breakBoth = "
"; breakHtmlOnly = "
"; breakTextOnly = ""; brief = "\\brief "; + classStart = "\\class "; + classStop = ""; + codeWord = "\\p "; commentStart = "/*!\n"; commentStop = "*/\n"; + copyDoc = "\\copydoc "; flagSpanStart = ""; flagSpanStop = ""; - functionStart = "\\class "; + functionStart = "\\fn "; functionStop = ""; headingStart = "

"; headingStop = "

"; @@ -129,14 +150,21 @@ SetMarkup (bool outputText) listStop = ""; listLineStart = "
  • "; listLineStop = "
    • "; - reference = "\\ref "; + reference = " \\ref "; + returns = "\\returns "; sectionStart = "\\ingroup "; + seeAlso = "\\see "; subSectionStart = "\\addtogroup "; temporaryCharacter = "%"; + variable = "\\var "; } } // SetMarkup () +/*************************************************************** + * Docs for a single TypeId + ***************************************************************/ + /** * Print direct Attributes for this TypeId. * @@ -170,14 +198,15 @@ PrintAttributesTid (std::ostream &os, const TypeId tid) os << " " << listLineStart << "Underlying type: "; - if ( (info.checker->GetValueTypeName () != "ns3::EnumValue") - && (info.checker->GetUnderlyingTypeInformation () != "std::string") - ) + + std::string valType = info.checker->GetValueTypeName (); + std::string underType = info.checker->GetUnderlyingTypeInformation (); + if ((valType != "ns3::EnumValue") && (underType != "std::string")) { - // Two indirect cases to handle + // Indirect cases to handle bool handled = false; - - if (info.checker->GetValueTypeName () == "ns3::PointerValue") + + if (valType == "ns3::PointerValue") { const PointerChecker *ptrChecker = dynamic_cast (PeekPointer (info.checker)); @@ -189,7 +218,7 @@ PrintAttributesTid (std::ostream &os, const TypeId tid) handled = true; } } - else if (info.checker->GetValueTypeName () == "ns3::ObjectPtrContainerValue") + else if (valType == "ns3::ObjectPtrContainerValue") { const ObjectPtrContainerChecker * ptrChecker = dynamic_cast (PeekPointer (info.checker)); @@ -201,9 +230,35 @@ PrintAttributesTid (std::ostream &os, const TypeId tid) handled = true; } } + // Helper to match first part of string + class StringBeginMatcher + { + public: + StringBeginMatcher (const std::string s) + : m_string (s) { }; + bool operator () (const std::string t) + { + std::size_t pos = m_string.find (t); + return pos == 0; + }; + private: + std::string m_string; + }; + StringBeginMatcher match (underType); + + if ( match ("bool") || match ("double") || + match ("int8_t") || match ("uint8_t") || + match ("int16_t") || match ("uint16_t") || + match ("int32_t") || match ("uint32_t") || + match ("int64_t") || match ("uint64_t") + ) + { + os << underType; + handled = true; + } if (! handled) { - os << reference << info.checker->GetUnderlyingTypeInformation (); + os << reference << underType; } } os << listLineStop << std::endl; @@ -237,7 +292,7 @@ PrintAttributesTid (std::ostream &os, const TypeId tid) } os << listStop << std::endl; -} +} // PrintAttributesTid () /** @@ -314,7 +369,7 @@ PrintTraceSourcesTid (std::ostream & os, const TypeId tid) os << listLineStop << std::endl; } os << listStop << std::endl; -} +} // PrintTraceSourcesTid () /** @@ -379,48 +434,12 @@ void PrintSize (std::ostream & os, const TypeId tid) << " of this type is " << tid.GetSize () << " bytes (on a " << arch << "-bit architecture)." << std::endl; -} +} // PrintSize () -/** - * Print the list of all Trace sources. - * - * \param [in,out] os The output stream. - */ -void -PrintAllTraceSources (std::ostream & os) -{ - NS_LOG_FUNCTION_NOARGS (); - os << commentStart << page << "TraceSourceList All TraceSources\n" - << std::endl; - - for (uint32_t i = 0; i < TypeId::GetRegisteredN (); ++i) - { - TypeId tid = TypeId::GetRegistered (i); - if (tid.GetTraceSourceN () == 0 || - tid.MustHideFromDocumentation ()) - { - continue; - } - os << boldStart << tid.GetName () << boldStop << breakHtmlOnly - << std::endl; - - os << listStart << std::endl; - for (uint32_t j = 0; j < tid.GetTraceSourceN (); ++j) - { - struct TypeId::TraceSourceInformation info = tid.GetTraceSource(j); - os << listLineStart - << boldStart << info.name << boldStop - << ": " << info.help - << listLineStop - << std::endl; - } - os << listStop << std::endl; - } - os << commentStop << std::endl; - -} // PrintAllTraceSources () - +/*************************************************************** + * Lists of All things + ***************************************************************/ /** * Print the list of all Attributes. @@ -433,6 +452,11 @@ PrintAllAttributes (std::ostream & os) NS_LOG_FUNCTION_NOARGS (); os << commentStart << page << "AttributeList All Attributes\n" << std::endl; + os << "This is a list of all" << reference << "attribute by class. " + << "For more information see the" << reference << "attribute " + << "section of this API documentation and the Attributes sections " + << "in the Tutorial and Manual.\n" + << std::endl; for (uint32_t i = 0; i < TypeId::GetRegisteredN (); ++i) { @@ -473,6 +497,8 @@ PrintAllGlobals (std::ostream & os) NS_LOG_FUNCTION_NOARGS (); os << commentStart << page << "GlobalValueList All GlobalValues\n" << std::endl; + os << "This is a list of all" << reference << "ns3::GlobalValue instances.\n" + << std::endl; os << listStart << std::endl; for (GlobalValue::Iterator i = GlobalValue::Begin (); @@ -509,6 +535,8 @@ PrintAllLogComponents (std::ostream & os) NS_LOG_FUNCTION_NOARGS (); os << commentStart << page << "LogComponentList All LogComponents\n" << std::endl; + os << "This is a list of all" << reference << "ns3::LogComponent instances.\n" + << std::endl; os << listStart << std::endl; LogComponent::ComponentList * logs = LogComponent::GetComponentList (); @@ -516,7 +544,8 @@ PrintAllLogComponents (std::ostream & os) for (it = logs->begin (); it != logs->end (); ++it) { std::string file = it->second->File (); - if (file.find ("../") == 0) + // Strip leading "../" related to depth in build directory + while (file.find ("../") == 0) { file = file.substr (3); } @@ -528,9 +557,377 @@ PrintAllLogComponents (std::ostream & os) } os << listStop << std::endl; os << commentStop << std::endl; -} // PrintAllLogComponents +} // PrintAllLogComponents () +/** + * Print the list of all Trace sources. + * + * \param [in,out] os The output stream. + */ +void +PrintAllTraceSources (std::ostream & os) +{ + NS_LOG_FUNCTION_NOARGS (); + os << commentStart << page << "TraceSourceList All TraceSources\n" + << std::endl; + os << "This is a list of all" << reference << "tracing sources. " + << "For more information see the " << reference << "tracing " + << "section of this API documentation and the Tracing sections " + << "in the Tutorial and Manual.\n" + << std::endl; + + for (uint32_t i = 0; i < TypeId::GetRegisteredN (); ++i) + { + TypeId tid = TypeId::GetRegistered (i); + if (tid.GetTraceSourceN () == 0 || + tid.MustHideFromDocumentation ()) + { + continue; + } + os << boldStart << tid.GetName () << boldStop << breakHtmlOnly + << std::endl; + + os << listStart << std::endl; + for (uint32_t j = 0; j < tid.GetTraceSourceN (); ++j) + { + struct TypeId::TraceSourceInformation info = tid.GetTraceSource(j); + os << listLineStart + << boldStart << info.name << boldStop + << ": " << info.help + << listLineStop + << std::endl; + } + os << listStop << std::endl; + } + os << commentStop << std::endl; + +} // PrintAllTraceSources () + + +/*************************************************************** + * Docs for Attribute classes + ***************************************************************/ + + +/** + * Print the section definition for an AttributeValue. + * + * In doxygen form this will print a comment block with + * \verbatim + * \ingroup attribute + * \defgroup attribute_Value Value + * \endverbatim + * + * \param [in,out] os The output stream. + * \param [in] name The base name of the resulting AttributeValue type. + * \param [in] seeBase Print a "see also" pointing to the base class. + */ +void +PrintAttributeValueSection (std::ostream & os, + const std::string & name, + const bool seeBase = true) +{ + NS_LOG_FUNCTION (name); + std::string section = "attribute_" + name; + + // \ingroup attribute + // \defgroup attribute_Value Attribute + os << commentStart << sectionStart << "attribute\n" + << subSectionStart << "attribute_" << name << " " + << name << " Attribute\n" + << "Attribute implementation for " << name << "\n"; + if (seeBase) + { + // Some classes don't live in ns3::. Yuck + if (name != "IeMeshId") + { + os << seeAlso << "ns3::" << name << "\n"; + } + else + { + os << seeAlso << "ns3::dot11s::" << name << "\n"; + } + } + os << commentStop; + +} // PrintAttributeValueSection () + + +/** + * Print the AttributeValue documentation for a class. + * + * This will print documentation for the \p Value class and methods. + * + * \param [in,out] os The output stream. + * \param [in] name The token to use in defining the accessor name. + * \param [in] type The underlying type name. + * \param [in] header The header file which contains this declaration. + */ +void +PrintAttributeValueWithName (std::ostream & os, + const std::string & name, + const std::string & type, + const std::string & header) +{ + NS_LOG_FUNCTION (name << type << header); + std::string sectAttr = sectionStart + "attribute_" + name; + + // \ingroup attribute_Value + // \class ns3::Value "header" + std::string valClass = name + "Value"; + std::string qualClass = " ns3::" + valClass; + + os << commentStart << sectAttr << std::endl; + os << classStart << qualClass << " \"" << header << "\"" << std::endl; + os << "AttributeValue implementation for " << name << "." << std::endl; + os << seeAlso << "AttributeValue" << std::endl; + os << commentStop; + + // Copy ctor: Value::Value + os << commentStart + << functionStart << name + << qualClass << "::" << valClass; + if ( (name == "EmptyAttribute") || + (name == "ObjectPtrContainer") ) + { + // Just default constructors. + os << "(void)\n"; + } + else + { + // Copy constructors + os << "(const " << type << " & value)\n" + << "Copy constructor.\n" + << argument << "[in] value The " << name << " value to copy.\n"; + } + os << commentStop; + + // Value::Get (void) const + os << commentStart + << functionStart << type + << qualClass << "::Get (void) const\n" + << returns << "The " << name << " value.\n" + << commentStop; + + // Value::GetAccessor (T & value) const + os << commentStart + << functionStart << "bool" + << qualClass << "::GetAccessor (T & value) const\n" + << "Access the " << name << " value as type " << codeWord << "T.\n" + << argument << "[out] value The " << name << " value, as type " + << codeWord << "T.\n" + << returns << "true.\n" + << commentStop; + + // Value::Set (const name & value) + if (type != "Callback") // Yuck + { + os << commentStart + << functionStart << "void" + << qualClass << "::Set (const " << type << " & value)\n" + << "Set the value.\n" + << argument << "[in] value The value to adopt.\n" + << commentStop; + } + + // Value::m_value + os << commentStart + << variable << type + << qualClass << "::m_value\n" + << "The stored " << name << " instance.\n" + << commentStop + << std::endl; + +} // PrintAttributeValueWithName () + + +/** + * Print the AttributeValue MakeAccessor documentation for a class. + * + * This will print documentation for the \p MakeAccessor functions. + * + * \param [in,out] os The output stream. + * \param [in] name The token to use in defining the accessor name. + */ +void +PrintMakeAccessors (std::ostream & os, const std::string & name) +{ + NS_LOG_FUNCTION (name); + std::string sectAttr = sectionStart + "attribute_" + name + "\n"; + std::string make = "ns3::Make" + name + "Accessor "; + + // \ingroup attribute_Value + // MakeAccessor (T1 a1) + os << commentStart << sectAttr + << functionStart << "ns3::Ptr " + << make << "(T1 a1)\n" + << copyDoc << "ns3::MakeAccessorHelper(T1)\n" + << seeAlso << "AttributeAccessor\n" + << commentStop; + + // \ingroup attribute_Value + // MakeAccessor (T1 a1) + os << commentStart << sectAttr + << functionStart << "ns3::Ptr " + << make << "(T1 a1, T2 a2)\n" + << copyDoc << "ns3::MakeAccessorHelper(T1,T2)\n" + << seeAlso << "AttributeAccessor\n" + << commentStop; +} // PrintMakeAccessors () + + +/** + * Print the AttributeValue MakeChecker documentation for a class. + * + * This will print documentation for the \p MakeChecker function. + * + * \param [in,out] os The output stream. + * \param [in] name The token to use in defining the accessor name. + * \param [in] header The header file which contains this declaration. + */ +void +PrintMakeChecker (std::ostream & os, + const std::string & name, + const std::string & header) +{ + NS_LOG_FUNCTION (name << header); + std::string sectAttr = sectionStart + "attribute_" + name + "\n"; + std::string make = "ns3::Make" + name + "Checker "; + + // \ingroup attribute_Value + // class Checker + os << commentStart << sectAttr << std::endl; + os << classStart << " ns3::" << name << "Checker" + << " \"" << header << "\"" << std::endl; + os << "AttributeChecker implementation for " << name << "Value." << std::endl; + os << seeAlso << "AttributeChecker" << std::endl; + os << commentStop; + + // \ingroup attribute_Value + // MakeChecker (void) + os << commentStart << sectAttr + << functionStart << "ns3::Ptr " + << make << "(void)\n" + << returns << "The AttributeChecker.\n" + << seeAlso << "AttributeChecker\n" + << commentStop; +} // PrintMakeChecker () + + +/**Descriptor for an AttributeValue. */ +typedef struct { + const std::string m_name; //!< The base name of the resulting AttributeValue type. + const std::string m_type; //!< The name of the underlying type. + const bool m_seeBase; //!< Print a "see also" pointing to the base class. + const std::string m_header; //!< The header file name. +} AttributeDescriptor; + + +/** + * Print documentation corresponding to use of the + * ATTRIBUTE_HELPER_HEADER macro or + * ATTRIBUTE_VALUE_DEFINE_WITH_NAME macro. + * + * \param [in,out] os The output stream. + * \param [in] attr The AttributeDescriptor. + */ +void +PrintAttributeHelper (std::ostream & os, + const AttributeDescriptor & attr) +{ + NS_LOG_FUNCTION (attr.m_name << attr.m_type << attr.m_seeBase << + attr.m_header); + PrintAttributeValueSection (os, attr.m_name, attr.m_seeBase); + PrintAttributeValueWithName (os, attr.m_name, attr.m_type, attr.m_header); + PrintMakeAccessors (os, attr.m_name); + PrintMakeChecker (os, attr.m_name, attr.m_header); +} // PrintAttributeHelper () + + +/** + * Print documentation for Attribute implementations. + */ +void +PrintAttributeImplementations (std::ostream & os) +{ + NS_LOG_FUNCTION_NOARGS (); + + const AttributeDescriptor attributes [] = + { + // Users of ATTRIBUTE_HELPER_HEADER + // + { "Address", "Address", true, "address.h" }, + { "Box", "Box", true, "box.h" }, + { "DataRate", "DataRate", true, "data-rate.h" }, + { "HtCapabilities", "HtCapabilities", true, "ht-capabilities.h" }, + { "IeMeshId", "IeMeshId", true, "id-dot11s-id.h" }, + { "Ipv4Address", "Ipv4Address", true, "ipv4-address.h" }, + { "Ipv4Mask", "Ipv4Mask", true, "ipv4-address.h" }, + { "Ipv6Address", "Ipv6Address", true, "ipv6-address.h" }, + { "Ipv6Prefix", "Ipv6Prefix", true, "ipv6-address.h" }, + { "Mac16Address", "Mac16Address", true, "mac16-address.h" }, + { "Mac48Address", "Mac48Address", true, "mac48-address.h" }, + { "Mac64Address", "Mac64Address", true, "mac64-address.h" }, + { "ObjectFactory", "ObjectFactory", true, "object-factory.h" }, + { "OrganizationIdentifier", + "OrganizationIdentifier", + true, "vendor-specific-action.h" }, + { "Rectangle", "Rectangle", true, "rectangle.h" }, + { "Ssid", "Ssid", true, "ssid.h" }, + { "TypeId", "TypeId", true, "type-id.h" }, + { "UanModesList", "UanModesList", true, "uan-tx-mode.h" }, + { "ValueClassTest", "ValueClassTest", false, "" /* outside ns3 */ }, + { "Vector2D", "Vector2D", true, "vector.h" }, + { "Vector3D", "Vector3D", true, "vector.h" }, + { "Waypoint", "Waypoint", true, "waypoint.h" }, + { "WifiMode", "WifiMode", true, "wifi-mode.h" }, + + // All three (Value, Access and Checkers) defined, but custom + { "Boolean", "Boolean", false, "boolean.h" }, + { "Callback", "Callback", true, "callback.h" }, + { "Double", "double", false, "double.h" }, + { "Enum", "int", false, "enum.h" }, + { "Integer", "int64_t", false, "integer.h" }, + { "Pointer", "Pointer", false, "pointer.h" }, + { "RandomVariable", "RandomVariable", true, "random-variable.h" }, + { "String", "std::string", false, "string.h" }, + { "Time", "Time", true, "nstime.h" }, + { "Uinteger", "uint64_t", false, "uinteger.h" }, + { "", "", false, "last placeholder" } + }; + + int i = 0; + while (attributes[i].m_name != "") + { + PrintAttributeHelper (os, attributes[i]); + ++i; + } + + // Special cases + PrintAttributeValueSection (os, "EmptyAttribute", false); + PrintAttributeValueWithName (os, "EmptyAttribute", "EmptyAttribute", + "attribute.h"); + + PrintAttributeValueSection (os, "ObjectPtrContainer", false); + PrintAttributeValueWithName (os, "ObjectPtrContainer", "ObjectPtrContainer", "object-ptr-container.h"); + PrintMakeChecker (os, "ObjectPtrContainer", "object-ptr-container.h"); + + PrintAttributeValueSection (os, "ObjectVector", false); + PrintMakeAccessors (os, "ObjectVector"); + PrintMakeChecker (os, "ObjectVector", "object-vector.h"); + + PrintAttributeValueSection (os, "ObjectMap", false); + PrintMakeAccessors (os, "ObjectMap"); + PrintMakeChecker (os, "ObjectMap", "object-map.h"); + +} // PrintAttributeImplementations () + + +/*************************************************************** + * Aggregation and configuration paths + ***************************************************************/ + /** * Gather aggregation and configuration path information from registered types. */ @@ -609,7 +1006,7 @@ private: * List of aggregation relationships. */ std::vector > m_aggregates; -}; +}; // class StaticInformation void @@ -798,7 +1195,7 @@ StaticInformation::DoGather (TypeId tid) m_currentPath.pop_back (); } } -} +} // StaticInformation::DoGather () void @@ -928,9 +1325,13 @@ PrintConfigPaths (std::ostream & os, const StaticInformation & info, } os << listStop << std::endl; } -} // PrintConfigPaths +} // PrintConfigPaths () +/*************************************************************** + * Main + ***************************************************************/ + int main (int argc, char *argv[]) { NS_LOG_FUNCTION_NOARGS (); @@ -979,7 +1380,7 @@ int main (int argc, char *argv[]) continue; } - std::cout << functionStart << tid.GetName () << std::endl; + std::cout << classStart << tid.GetName () << std::endl; std::cout << std::endl; PrintConfigPaths (std::cout, info, tid); @@ -995,6 +1396,7 @@ int main (int argc, char *argv[]) PrintAllGlobals (std::cout); PrintAllLogComponents (std::cout); PrintAllTraceSources (std::cout); + PrintAttributeImplementations (std::cout); return 0; }