diff --git a/src/core/helper/csv-reader.h b/src/core/helper/csv-reader.h index 154a5f535..23b49f615 100644 --- a/src/core/helper/csv-reader.h +++ b/src/core/helper/csv-reader.h @@ -40,7 +40,7 @@ namespace ns3 { /** * \ingroup core - * \defgroup csvreader + * \defgroup csvreader CSV File Reader * * A way to extract data from simple csv files. */ diff --git a/src/core/model/attribute.cc b/src/core/model/attribute.cc index 159a85cce..ceedfe73c 100644 --- a/src/core/model/attribute.cc +++ b/src/core/model/attribute.cc @@ -25,7 +25,7 @@ /** * \file - * \ingroup attribute + * \ingroup attributes * ns3::AttributeValue, ns3::AttributeAccessor and * ns3::AttributeChecker implementations. */ diff --git a/src/core/model/attribute.h b/src/core/model/attribute.h index d2772fdde..970fb9e5e 100644 --- a/src/core/model/attribute.h +++ b/src/core/model/attribute.h @@ -27,7 +27,7 @@ /** * \file - * \ingroup attribute + * \ingroup attributes * ns3::AttributeValue, ns3::AttributeAccessor and * ns3::AttributeChecker declarations. */ diff --git a/src/core/model/calendar-scheduler.h b/src/core/model/calendar-scheduler.h index c3a108133..a91788257 100644 --- a/src/core/model/calendar-scheduler.h +++ b/src/core/model/calendar-scheduler.h @@ -204,7 +204,7 @@ private: * Ordering function to identify the insertion point, according to \c m_reverse. * \param [in] newEvent The new event being inserted. * \param [in] it The current position in the bucket being examined. - * \return \c true if the \c newEvent belongs before \it. + * \return \c true if the \c newEvent belongs before \c it. */ bool (*Order) (const EventKey & newEvent, const EventKey & it); /** diff --git a/src/core/model/callback.h b/src/core/model/callback.h index 06c1de243..e16e597b0 100644 --- a/src/core/model/callback.h +++ b/src/core/model/callback.h @@ -1572,7 +1572,13 @@ private: return false; } } - /** \copydoc Assign(const CallbackBase&). */ + /* Broken: \copydoc Callback::Assign() */ + /** + * Adopt the other's implementation, if type compatible + * + * \param [in] other Callback + * \returns \c true if \pname{other} was type-compatible and could be adopted. + */ bool DoAssign (Ptr other) { if (!DoCheckType (other)) @@ -1948,13 +1954,7 @@ public: virtual ~CallbackValue (); /** \param [in] base The CallbackBase to use */ void Set (CallbackBase base); - /** - * Give value my callback, if type compatible - * - * \tparam T \deduced The type in which to retrieve the value. - * \param [out] value Destination callback - * \returns \c true if successful - */ + /* Documented by print-introspected-doxygen.cc */ template bool GetAccessor (T &value) const; /** \return A copy of this CallBack */ @@ -1975,7 +1975,8 @@ public: virtual bool DeserializeFromString (std::string value, Ptr checker); private: - CallbackBase m_value; //!< the CallbackBase + /* Documented by print-introspected-doxygen.cc */ + CallbackBase m_value; }; ATTRIBUTE_ACCESSOR_DEFINE (Callback); diff --git a/src/core/model/config.cc b/src/core/model/config.cc index 50ed341fd..5a324dd00 100644 --- a/src/core/model/config.cc +++ b/src/core/model/config.cc @@ -619,29 +619,29 @@ class ConfigImpl : public Singleton public: // Keep Set and SetFailSafe since their errors are triggered // by the underlying ObjecBase functions. - /** \copydoc Config::Set() */ + /** \copydoc ns3::Config::Set() */ void Set (std::string path, const AttributeValue &value); - /** \copydoc Config::SetFailSafe() */ + /** \copydoc ns3::Config::SetFailSafe() */ bool SetFailSafe (std::string path, const AttributeValue &value); - /** \copydoc Config::ConnectWithoutContextFailSafe() */ + /** \copydoc ns3::Config::ConnectWithoutContextFailSafe() */ bool ConnectWithoutContextFailSafe (std::string path, const CallbackBase &cb); - /** \copydoc Config::ConnectFailSafe() */ + /** \copydoc ns3::Config::ConnectFailSafe() */ bool ConnectFailSafe (std::string path, const CallbackBase &cb); - /** \copydoc Config::DisconnectWithoutContext() */ + /** \copydoc ns3::Config::DisconnectWithoutContext() */ void DisconnectWithoutContext (std::string path, const CallbackBase &cb); - /** \copydoc Config::Disconnect() */ + /** \copydoc ns3::Config::Disconnect() */ void Disconnect (std::string path, const CallbackBase &cb); - /** \copydoc Config::LookupMatches() */ + /** \copydoc ns3::Config::LookupMatches() */ MatchContainer LookupMatches (std::string path); - /** \copydoc Config::RegisterRootNamespaceObject() */ + /** \copydoc ns3::Config::RegisterRootNamespaceObject() */ void RegisterRootNamespaceObject (Ptr obj); - /** \copydoc Config::UnregisterRootNamespaceObject() */ + /** \copydoc ns3::Config::UnregisterRootNamespaceObject() */ void UnregisterRootNamespaceObject (Ptr obj); - /** \copydoc Config::GetRootNamespaceObjectN() */ + /** \copydoc ns3::Config::GetRootNamespaceObjectN() */ std::size_t GetRootNamespaceObjectN (void) const; - /** \copydoc Config::GetRootNamespaceObject() */ + /** \copydoc ns3::Config::GetRootNamespaceObject() */ Ptr GetRootNamespaceObject (std::size_t i) const; private: diff --git a/src/core/model/config.h b/src/core/model/config.h index 5d427bf5d..b2315967d 100644 --- a/src/core/model/config.h +++ b/src/core/model/config.h @@ -67,6 +67,10 @@ void Reset (void); */ void Set (std::string path, const AttributeValue &value); /** + * \ingroup config + * \param [in] path A path to match attributes. + * \param [in] value The value to set in all matching attributes. + * * This function will attempt to find attributes which * match the input path and will then set their value to the input * value, and will return true if at least one such attribute is found. @@ -123,6 +127,10 @@ bool SetGlobalFailSafe (std::string name, const AttributeValue &value); */ void ConnectWithoutContext (std::string path, const CallbackBase &cb); /** + * \ingroup config + * \param [in] path A path to match trace sources. + * \param [in] cb The callback to connect to the matching trace sources. + * * This function will attempt to find all trace sources which * match the input path and will then connect the input callback * to them. If no matching trace sources are found, this method will @@ -153,6 +161,10 @@ void DisconnectWithoutContext (std::string path, const CallbackBase &cb); */ void Connect (std::string path, const CallbackBase &cb); /** + * \ingroup config + * \param [in] path A path to match trace sources. + * \param [in] cb The callback to connect to the matching trace sources. + * * This function will attempt to find all trace sources which * match the input path and will then connect the input callback * to them in such a way that the callback will receive an extra @@ -196,16 +208,25 @@ public: /** * \returns An iterator which points to the first item in the container + * @{ */ MatchContainer::Iterator Begin (void) const; + MatchContainer::Iterator begin (void) const { return Begin (); } + /** @} */ /** * \returns An iterator which points to the last item in the container + * @{ */ MatchContainer::Iterator End (void) const; + MatchContainer::Iterator end (void) const { return End (); } + /** @} */ /** * \returns The number of items in the container + * @{ */ std::size_t GetN (void) const; + std::size_t size (void) const { return GetN (); } + /** @} */ /** * \param [in] i Index of item to lookup ([0,n[) * \returns The item requested. @@ -236,6 +257,9 @@ public: */ void Set (std::string name, const AttributeValue &value); /** + * \param [in] name Name of attribute to set + * \param [in] value Value to set to the attribute + * * Set the specified attribute value to all the objects stored in this * container. This method will return true if any attributes could be * set, and false otherwise. @@ -254,6 +278,9 @@ public: */ void Connect (std::string name, const CallbackBase &cb); /** + * \param [in] name The name of the trace source to connect to + * \param [in] cb The sink to connect to the trace source + * * Connect the specified sink to all the objects stored in this * container. This method will return true if any trace sources could be * connected, and false otherwise. @@ -272,6 +299,9 @@ public: */ void ConnectWithoutContext (std::string name, const CallbackBase &cb); /** + * \param [in] name The name of the trace source to connect to + * \param [in] cb The sink to connect to the trace source + * * Connect the specified sink to all the objects stored in this * container. This method will return true if any trace sources could be * connected, and false otherwise. diff --git a/src/core/model/enum.h b/src/core/model/enum.h index 475c6a14d..214f65194 100644 --- a/src/core/model/enum.h +++ b/src/core/model/enum.h @@ -155,6 +155,7 @@ Ptr MakeEnumAccessor (T1 a1, T2 a2); * \returns The AttributeChecker * \param [in] v The default enum value. * \param [in] n The corresponding name. + * \param [in] args Any additional arguments. */ template Ptr @@ -174,6 +175,7 @@ MakeEnumChecker (int v, std::string n, Ts... args) * \param [in] checker The AttributeChecker. * \param [in] v The next enum value. * \param [in] n The corresponding name. + * \param [in] args Any additional arguments. */ template @@ -187,7 +189,7 @@ MakeEnumChecker (Ptr checker, int v, std::string n, Ts... args) /** * Terminate the recursion of variadic arguments. * - * \returns The \pname checker + * \returns The \p checker * \param [in] checker The AttributeChecker. */ // inline to allow tail call optimization diff --git a/src/core/model/global-value.h b/src/core/model/global-value.h index f19bb72cc..5d258e632 100644 --- a/src/core/model/global-value.h +++ b/src/core/model/global-value.h @@ -108,7 +108,6 @@ public: * Get the value. * \param [out] value The AttributeValue to set to the value * of this GlobalValue - * \returns The current value of this GlobalValue. */ void GetValue (AttributeValue &value) const; /** diff --git a/src/core/model/int64x64-cairo.h b/src/core/model/int64x64-cairo.h index 53f95fd70..649e1f1f2 100644 --- a/src/core/model/int64x64-cairo.h +++ b/src/core/model/int64x64-cairo.h @@ -19,6 +19,7 @@ #include "ns3/core-config.h" #if !defined(INT64X64_CAIRO_H) && defined (INT64X64_USE_CAIRO) && !defined(PYTHON_SCAN) +/** Using the ns3::int64x64_t based on Cairo 128-bit integers. */ #define INT64X64_CAIRO_H #include // pow diff --git a/src/core/model/int64x64-double.h b/src/core/model/int64x64-double.h index 34cd9a464..fc6566123 100644 --- a/src/core/model/int64x64-double.h +++ b/src/core/model/int64x64-double.h @@ -19,6 +19,7 @@ #include "ns3/core-config.h" #if !defined(INT64X64_DOUBLE_H) && (defined (INT64X64_USE_DOUBLE) || defined(PYTHON_SCAN)) +/** Using the ns3::int64x64_t based on double values. */ #define INT64X64_DOUBLE_H #include @@ -280,8 +281,9 @@ private: /** * \name Arithmetic Operators * Arithmetic operators for int64x64_t. + * @{ */ - /** + /* * @{ * Arithmetic operator. * \param [in] lhs Left hand argument @@ -303,7 +305,7 @@ private: * \name Unary Operators * Unary operators for int64x64_t. */ - /** + /* * @{ * Unary operator. * \param [in] lhs Left hand argument @@ -318,7 +320,7 @@ private: }; // class int64x64_t -/** +/* * \ingroup highprec * Equality operator. * \param [in] lhs Left hand argument diff --git a/src/core/model/length.cc b/src/core/model/length.cc index 958d390eb..0174c39e3 100644 --- a/src/core/model/length.cc +++ b/src/core/model/length.cc @@ -18,7 +18,7 @@ * Author: Mathew Bielejeski */ -#include "length.h" +#include "ns3/length.h" #include "ns3/log.h" @@ -394,11 +394,6 @@ Length::As (Length::Unit unit) const return Quantity (value, unit); } -//silence doxygen warnings about undocumented functions -/** - * \ingroup length - * @{ - */ bool operator== (const Length& left, const Length& right) { diff --git a/src/core/model/length.h b/src/core/model/length.h index f7c3ee1ec..4534866c9 100644 --- a/src/core/model/length.h +++ b/src/core/model/length.h @@ -101,16 +101,16 @@ namespace ns3 { * abbreviated name (nm, km, ft, etc.). * * \code -//construct lengths from strings -Length foot ("1foot"); -Length cm ("1cm"); -Length mile ("1 mile"); -Length km ("1 km"); - -//nautical mile is special because it is two words -Length nautmile ("1 nautical mile"); -Length nmi ("1 nmi"); -\endcode + * //construct lengths from strings + * Length foot ("1foot"); + * Length cm ("1cm"); + * Length mile ("1 mile"); + * Length km ("1 km"); + * + * //nautical mile is special because it is two words + * Length nautmile ("1 nautical mile"); + * Length nmi ("1 nmi"); + * \endcode * * ### Quantity Constructor ### * @@ -120,10 +120,10 @@ Length nmi ("1 nmi"); * equivalent value in meters. * * \code -//construct a Length representing 2 kilometers -Length::Quantity q (2, Length::Unit::Kilometer); -Length km(q); -\endcode + * //construct a Length representing 2 kilometers + * Length::Quantity q (2, Length::Unit::Kilometer); + * Length km(q); + * \endcode * * ### Value/Unit Constructor * @@ -134,10 +134,10 @@ Length km(q); * Length::Unit * * \code -//These two contructors are equivalent -Length l1 (1, "cm"); -Length l2 (1, Length::Unit::Centimeter); -\endcode + * //These two contructors are equivalent + * Length l1 (1, "cm"); + * Length l2 (1, Length::Unit::Centimeter); + * \endcode * * ### boost::units * @@ -146,10 +146,11 @@ Length l2 (1, Length::Unit::Centimeter); * from boost::unit quantities. * * \code -//construct length from a boost::units quantitiy -boost::units::quantity q = 5 * boost::units::si::meter; -Length meters (q); -\endcode + * //construct length from a boost::units quantitiy + * boost::units::quantity q + * = 5 * boost::units::si::meter; + * Length meters (q); + * \endcode * * ## Arithmetic Operations ## * @@ -160,26 +161,28 @@ Length meters (q); * Addition is between two Length instances * * \code -std::cout << Length(1, Length::Unit::Meter) + Length (2, Length::Unit::Meter); // output: "3 m" -\endcode + * std::cout << Length(1, Length::Unit::Meter) + Length (2, Length::Unit::Meter); + * // output: "3 m" + * \endcode * * ### Subtraction ### * * Subtraction is between two Length instances * * \code -std::cout << Length(3, Length::Unit::Meter) - Length (2, Length::Unit::Meter); // output: "1 m" -\endcode + * std::cout << Length(3, Length::Unit::Meter) - Length (2, Length::Unit::Meter); + * // output: "1 m" + * \endcode * * ### Multiplication ### * * Multiplication is only supported between a Length and a unitless scalar value * * \code -std::cout << Length(1, Length::Unit::Meter) * 5; // output: "5 m" - -std::cout << 5 * Length (1, Length::Unit::Meter); // output: "5 m" -\endcode + * std::cout << Length(1, Length::Unit::Meter) * 5; // output: "5 m" + * + * std::cout << 5 * Length (1, Length::Unit::Meter); // output: "5 m" + * \endcode * * * ### Division ### @@ -191,10 +194,11 @@ std::cout << 5 * Length (1, Length::Unit::Meter); // output: "5 m" * Division between two Length objects returns a unitless value. * * \code -std::cout << Length(5, Length::Unit::Meter) / 5; // output: "1 m" - -std::cout << Length (5, Length::Unit::Meter) / Length (5, Length::Unit::Meter); // output: 1 -\endcode + * std::cout << Length(5, Length::Unit::Meter) / 5; // output: "1 m" + * + * std::cout << Length (5, Length::Unit::Meter) / Length (5, Length::Unit::Meter); + * // output: 1 + * \endcode * * ## Comparison Operations ## * @@ -207,19 +211,19 @@ std::cout << Length (5, Length::Unit::Meter) / Length (5, Length::Unit::Meter); * must match when performing the comparison. * * \code -//check for exact match -Length l (5, Length::Unit::Meter); - -bool match = (l == l); // match is true - -Length v1 (0.02, Length::Unit::Meter); -Length v2 (0.022, Length::Unit::Meter); - -match = (v1 == v2); // match is false - -double tolerance = 0.01; -bool mostly_match = v1.IsEqual (v2, tolerance); // mostly_match is true -\endcode + * //check for exact match + * Length l (5, Length::Unit::Meter); + * + * bool match = (l == l); // match is true + * + * Length v1 (0.02, Length::Unit::Meter); + * Length v2 (0.022, Length::Unit::Meter); + * + * match = (v1 == v2); // match is false + * + * double tolerance = 0.01; + * bool mostly_match = v1.IsEqual (v2, tolerance); // mostly_match is true + * \endcode * * ## Serialization ## * @@ -228,12 +232,13 @@ bool mostly_match = v1.IsEqual (v2, tolerance); // mostly_match is true * the Length value in a different unit. * * \code -Length m(5, Length::Unit::Meter); - -//output: 5 m, 0.005 km, 16.4042 ft -std::cout << m << ", " << m.As(Length::Unit::Kilometer) << ", " << m.As(Length::Unit::Foot); -\endcode + * Length m(5, Length::Unit::Meter); * + * std::cout << m << ", " + * << m.As(Length::Unit::Kilometer) << ", " + * << m.As(Length::Unit::Foot); + * //output: 5 m, 0.005 km, 16.4042 ft + * \endcode */ class Length { @@ -294,13 +299,17 @@ public: /** * Copy Assignment Operator + * \param [in] other The source to copy from. + * \returns this. */ - Quantity& operator= (const Quantity&) = default; + Quantity& operator= (const Quantity& other) = default; /** * Move Assignment Operator + * \param [in] other The source to move from. + * \returns this. */ - Quantity& operator= (Quantity&&) = default; + Quantity& operator= (Quantity&& other) = default; /** * The value of the quantity @@ -525,9 +534,9 @@ private: * values to still be considered equal * * Equivalent to: - \code - IsEqual(other, tolerance) || IsLess(other, tolerance) - \endcode + * \code + * IsEqual(other, tolerance) || IsLess(other, tolerance) + * \endcode * * \return true if the values are equal or \p other is * greater in value @@ -542,9 +551,9 @@ private: * values to still be considered equal * * Equivalent to: - \code - !(IsLessOrEqual(other, tolerance)) - \endcode + * \code + * !(IsLessOrEqual(other, tolerance)) + * \endcode * * \return true if the values are not equal and \p other is * less in value @@ -559,9 +568,9 @@ private: * values to still be considered equal * * Equivalent to: - \code - !IsLess(other, tolerance) - \endcode + * \code + * !IsLess(other, tolerance) + * \endcode * * \return true if the values are equal or \p other is * less in value @@ -574,11 +583,11 @@ private: * Swap the current value with the value in \p other. * * Equivalent to: - \code - Length temp(*this); - *this = other; - other = temp; - \endcode + * \code + * Length temp(*this); + * *this = other; + * other = temp; + * \endcode * * \param other Length object to swap */ @@ -588,9 +597,9 @@ private: * Current length value * * Equivalent to: - \code - As (Length::Unit::Meter).Value () - \endcode + * \code + * As (Length::Unit::Meter).Value () + * \endcode * \return The current value, in meters */ double GetDouble () const; @@ -611,13 +620,10 @@ private: double m_value; //!< Length in meters }; // class Length -/** - * Define LengthValue class to support using Length objects as attributes - */ ATTRIBUTE_HELPER_HEADER (Length); /** - * \relates Length + * \ingroup length * \brief Return the symbol of the supplied unit * * The symbol of the unit is the shortened form of the unit name and is usually @@ -630,7 +636,7 @@ ATTRIBUTE_HELPER_HEADER (Length); std::string ToSymbol (Length::Unit unit); /** - * \relates Length + * \ingroup length * \brief Return the name of the supplied unit * * The value returned by this function is the common name of \p unit. The output @@ -648,7 +654,7 @@ std::string ToSymbol (Length::Unit unit); std::string ToName (Length::Unit unit, bool plural = false); /** - * \relates Length + * \ingroup length * \brief Find the equivalent Length::Unit for a unit string * * The string value can be a symbol or name (plural or singular). @@ -669,14 +675,14 @@ std::string ToName (Length::Unit unit, bool plural = false); std::tuple FromString (std::string unitString); /** - * \relates Length + * \ingroup length * \brief Write a length value to an output stream. * * The output of the length is in meters. * * Equivalent to: * \code - * stream << l.As (Meter); + * stream << l.As (Meter); * \endcode * * \param stream Output stream @@ -687,15 +693,15 @@ std::tuple FromString (std::string unitString); std::ostream& operator<< (std::ostream& stream, const Length& l); /** - * \relates Length + * \ingroup length * \brief Write a Quantity to an output stream. * * The data written to the output stream will have the format \ \ * * Equivalent to: * \code -stream << q.Value () << ' ' << ToSymbol (q.Unit()); -\endcode + * stream << q.Value () << ' ' << ToSymbol (q.Unit()); + * \endcode * * \param stream Output stream * \param q Quantity to write to the output stream @@ -705,15 +711,15 @@ stream << q.Value () << ' ' << ToSymbol (q.Unit()); std::ostream& operator<< (std::ostream& stream, const Length::Quantity& q); /** - * \relates Length + * \ingroup length * \brief Write a Length::Unit to an output stream. * * Writes the name of \p unit to the output stream * * Equivalent to: * \code -stream << ToName (unit); -\endcode + * stream << ToName (unit); + * \endcode * * \param stream Output stream * \param unit Length unit to output @@ -723,7 +729,7 @@ stream << ToName (unit); std::ostream& operator<< (std::ostream& stream, Length::Unit unit); /** - * \relates Length + * \ingroup length * \brief Read a length value from an input stream. * * The expected format of the input is \ \ @@ -739,163 +745,162 @@ std::ostream& operator<< (std::ostream& stream, Length::Unit unit); std::istream& operator>> (std::istream& stream, Length& l); /** - * \relates Length + * \ingroup length * \brief Compare two length objects for equality. * * Equivalent to: * \code - * left.IsEqual(right, 0); + * left.IsEqual(right, 0); * \endcode * * \param left Left length object * \param right Right length object * - * \return true if \p l and \p r have the same value + * \return true if \p left and \p right have the same value */ bool operator== (const Length& left, const Length& right); /** - * \relates Length + * \ingroup length * \brief Compare two length objects for inequality. * * Equivalent to: * \code - * l.IsNotEqual(r, 0); + * left.IsNotEqual(right, 0); * \endcode * - * \param l Left length object - * \param r Right length object + * \param left Left length object + * \param right Right length object * - * \return true if \p l and \p r do not have the same value + * \return true if \p left and \p right do not have the same value */ -bool operator!= (const Length& l, const Length& r); +bool operator!= (const Length& left, const Length& right); /** - * \relates Length - * \brief Check if \p l has a value less than \p r + * \ingroup length + * \brief Check if \p left has a value less than \p right * * Equivalent to: * \code - * l.IsLess(r, 0); + * left.IsLess(right, 0); * \endcode * - * \param l Left length object - * \param r Right length object + * \param left Left length object + * \param right Right length object * - * \return true if \p l is less than \p r + * \return true if \p left is less than \p right */ -bool operator< (const Length& l, const Length& r); +bool operator< (const Length& left, const Length& right); /** - * \relates Length - * \brief Check if \p l has a value less than or equal to \p r + * \ingroup length + * \brief Check if \p left has a value less than or equal to \p right * * Equivalent to: * \code - * l.IsLessOrEqual(r, 0); + * left.IsLessOrEqual(right, 0); * \endcode * - * \param l Left length object - * \param r Right length object + * \param left Left length object + * \param right Right length object * - * \return true if \p l is less than or equal to \p r + * \return true if \p left is less than or equal to \p right */ -bool operator<= (const Length& l, const Length& r); +bool operator<= (const Length& left, const Length& right); /** - * \relates Length - * \brief Check if \p l has a value greater than \p r + * \ingroup length + * \brief Check if \p left has a value greater than \p right * * Equivalent to: * \code - * l.IsGreater(r, 0); + * left.IsGreater(right, 0); * \endcode * - * \param l Left length object - * \param r Right length object + * \param left Left length object + * \param right Right length object * - * \return true if \p l is greater than \p r + * \return true if \p left is greater than \p right */ -bool operator> (const Length& l, const Length& r); +bool operator> (const Length& left, const Length& right); /** - * \relates Length - * \brief Check if \p l has a value greater than or equal to \p r + * \ingroup length + * \brief Check if \p left has a value greater than or equal to \p right * * Equivalent to: * \code - * l.IsGreaterOrEqual(r, 0); + * left.IsGreaterOrEqual(right, 0); * \endcode * - * \param l Left length object - * \param r Right length object + * \param left Left length object + * \param right Right length object * - * \return true if \p l is greater than or equal to \p r + * \return true if \p left is greater than or equal to \p right */ -bool operator>= (const Length& l, const Length& r); +bool operator>= (const Length& left, const Length& right); /** - * \relates Length + * \ingroup length * \brief Add two length values together. * - * Adds the values of \p first to \p second and returns a new + * Adds the values of \p left to \p right and returns a new * Length object containing the result. * - * \param first A Length object - * \param second A Length object + * \param left A Length object + * \param right A Length object * * \return A newly constructed Length object containing the - * result of first + second + * result of `left + right`. */ -Length operator+ (const Length& first, const Length& second); +Length operator+ (const Length& left, const Length& right); /** - * \relates Length + * \ingroup length * \brief Subtract two length values. * - * Subtracts the value of \p second from \p first and returns a + * Subtracts the value of \p right from \p left and returns a * new Length object containing the result. * - * \param first A Length object - * \param second A Length object + * \param left A Length object + * \param right A Length object * * \return A newly constructed Length object containing the - * result of first - second + * result of `left - right`. */ -Length operator- (const Length& first, const Length& second); +Length operator- (const Length& left, const Length& right); /** - * \relates Length + * \ingroup length * \brief Multiply a length value by a scalar * - * Multiplies the value \p right by \p scalar and returns a new + * Multiplies the value \p l by \p scalar and returns a new * Length object containing the result. * - * \param scalar Multiplication factor - * \param right Length value - * - * \return A newly constructed Length object containing the result - * of right * scalar. - */ -Length operator* (double scalar, const Length& right); - -/** - * \relates Length - * \brief Multiply a length value by a scalar - * - * Multiplies the value \p left by \p scalar and returns a new - * Length object containing the result. - * - * \param left Length value + * \param l The Length object * \param scalar Multiplication factor * * \return A newly constructed Length object containing the result - * of left * scalar. + * of `l * scalar`. */ -Length operator* (const Length& left, double scalar); +Length operator* (double scalar, const Length& l); +/** + * \ingroup length + * \brief Multiply a length value by a scalar + * + * Multiplies the value \p l by \p scalar and returns a new + * Length object containing the result. + * + * \param l The Length object + * \param scalar Multiplication factor + * + * \return A newly constructed Length object containing the result + * of `l * scalar`. + */ +Length operator* (const Length& l, double scalar); /** - * \relates Length + * \ingroup length * \brief Divide a length value by a scalar * * Divides the value \p left by \p scalar and returns a new @@ -908,12 +913,12 @@ Length operator* (const Length& left, double scalar); * \param scalar Multiplication factor * * \return A newly constructed Length object containing the result - * of left / scalar. + * of `left / scalar`. */ Length operator/ (const Length& left, double scalar); /** - * \relates Length + * \ingroup length * \brief Divide a length value by another length value * * Divides the value \p numerator by the value \p denominator and @@ -924,17 +929,17 @@ Length operator/ (const Length& left, double scalar); * \param numerator The top value of the division * \param denominator The bottom value of the division * - * \return A scalar value that is the result of numerator / denominator or - * NaN if \p denominator is 0 + * \return A scalar value that is the result of `numerator / denominator` or + * NaN if \p denominator is 0. */ double operator/ (const Length& numerator, const Length& denominator); /** - * \relates Length + * \ingroup length * \brief Calculate how many times \p numerator can be split into \p denominator * sized pieces. * - * If the result of \p numerator / \p denominator is not a whole number, the + * If the result of `numerator / denominator` is not a whole number, the * result is rounded toward zero to the nearest whole number. * The amount remaining after the division can be retrieved by passing a pointer * to a Length in \p remainder. The remainder will be less than \p denominator @@ -952,7 +957,7 @@ double operator/ (const Length& numerator, const Length& denominator); int64_t Div (const Length& numerator, const Length& denominator, Length* remainder = nullptr); /** - * \relates Length + * \ingroup length * \brief Calculate the amount remaining after dividing two lengths * * The returned value will be less than \p denominator and have the same sign as @@ -969,107 +974,22 @@ int64_t Div (const Length& numerator, const Length& denominator, Length* remaind Length Mod (const Length& numerator, const Length& denominator); /** + * Construct a length from a value in the indicated unit. + * @{ * \ingroup length - * \relates Length - */ -/**@{*/ -/** - * Construct a Length from nanometers - * - * \param value Value in nanometers - * - * \return Length object constructed using Length::Unit::Nanometer + * \param value The numerical value. + * \returns Length object. */ Length NanoMeters (double value); - -/** - * Construct a Length from micrometers - * - * \param value Value in micrometers - * - * \return Length object constructed using Length::Unit::Micrometer - */ Length MicroMeters (double value); - -/** - * Construct a Length from millimeters - * - * \param value Value in millimeters - * - * \return Length object constructed using Length::Unit::Millimeter - */ Length MilliMeters (double value); - -/** - * Construct a Length from centimeters - * - * \param value Value in centimeters - * - * \return Length object constructed using Length::Unit::Centimeter - */ Length CentiMeters (double value); - -/** - * Construct a Length from meters - * - * \param value Value in meters - * - * \return Length object constructed using Length::Unit::Meter - */ Length Meters (double value); - -/** - * Construct a Length from kilometers - * - * \param value Value in kilometers - * - * \return Length object constructed using Length::Unit::Kilometer - */ Length KiloMeters (double value); - -/** - * Construct a Length from nautical miles - * - * \param value Value in nautical miles - * - * \return Length object constructed using Length::Unit::NauticalMile - */ Length NauticalMiles (double value); - -/** - * Construct a Length from inches - * - * \param value Value in inches - * - * \return Length object constructed using Length::Unit::Inch - */ Length Inches (double value); - -/** - * Construct a Length from feet - * - * \param value Value in feet - * - * \return Length object constructed using Length::Unit::Foot - */ Length Feet (double value); - -/** - * Construct a Length from yards - * - * \param value Value in yards - * - * \return Length object constructed using Length::Unit::Yard - */ Length Yards (double value); - -/** - * Construct a Length from miles - * - * \param value Value in miles - * - * \return Length object constructed using Length::Unit::Mile - */ Length Miles (double value); /**@}*/ diff --git a/src/core/model/nstime.h b/src/core/model/nstime.h index 1a9f18dea..e857f8a93 100644 --- a/src/core/model/nstime.h +++ b/src/core/model/nstime.h @@ -549,6 +549,7 @@ public: /** * Round a Time to a specific unit. * Rounding is to nearest integer. + * \param [in] unit The unit to round to. * \return The Time rounded to the specific unit. */ Time RoundTo (enum Unit unit) const @@ -723,7 +724,8 @@ private: friend bool operator < (const Time & lhs, const Time & rhs); friend bool operator > (const Time & lhs, const Time & rhs); friend bool operator < (const Time & time, const EventId & event); - /**@}*/ + /**@}*/ // Comparison operators + /** * \name Arithmetic operators * @{ @@ -732,70 +734,49 @@ private: friend Time operator - (const Time & lhs, const Time & rhs); friend Time operator * (const Time & lhs, const int64x64_t & rhs); friend Time operator * (const int64x64_t & lhs, const Time & rhs); + friend int64x64_t operator / (const Time & lhs, const Time & rhs); + friend Time operator / (const Time & lhs, const int64x64_t & rhs); + friend Time operator % (const Time & lhs, const Time & rhs); + friend int64_t Div (const Time & lhs, const Time & rhs); + friend Time Rem (const Time & lhs, const Time & rhs); template friend typename std::enable_if::value, Time>::type operator * (const Time& lhs, T rhs); - //this function uses is_arithmetic because it can be used by both - //integers and decimal types - /** - * Limited to \c is_arithmetic matches for the T argument to reduce the chances - * of matching some arbitrary object type. - */ + // Reversed arg version (forwards to `rhs * lhs`) + // Accepts both integers and decimal types template friend typename std::enable_if::value, Time>::type operator * (T lhs, const Time& rhs); - template - friend typename std::enable_if::value, Time>::type - operator * (const Time& lhs, T rhs); - - friend int64x64_t operator / (const Time & lhs, const Time & rhs); - friend Time operator / (const Time & lhs, const int64x64_t & rhs); - template friend typename std::enable_if::value, Time>::type operator / (const Time& lhs, T rhs); + friend Time Abs (const Time & time); + friend Time Max (const Time & timeA, const Time & timeB); + friend Time Min (const Time & timeA, const Time & timeB); + + /**@}*/ // Arithmetic operators + + // Leave undocumented + template + friend typename std::enable_if::value, Time>::type + operator * (const Time& lhs, T rhs); template friend typename std::enable_if::value, Time>::type operator / (const Time& lhs, T rhs); - friend Time operator % (const Time & lhs, const Time & rhs); - friend int64_t Div (const Time & lhs, const Time & rhs); - friend Time Rem (const Time & lhs, const Time & rhs); - /**@}*/ /** * \name Compound assignment operators * @{ */ friend Time & operator += (Time & lhs, const Time & rhs); friend Time & operator -= (Time & lhs, const Time & rhs); - /**@}*/ + /**@}*/ // Compound assignment - /** - * Absolute value function for Time - * \param [in] time The input value - * \returns The absolute value of the input value - */ - friend Time Abs (const Time & time); - /** - * Max function for Time. - * \param [in] timeA The first value - * \param [in] timeB The seconds value - * \returns The max of the two input values. - */ - friend Time Max (const Time & timeA, const Time & timeB); - /** - * Min function for Time. - * \param [in] timeA The first value - * \param [in] timeB The seconds value - * \returns The min of the two input values. - */ - friend Time Min (const Time & timeA, const Time & timeB); - int64_t m_data; //!< Virtual time value, in the current unit. @@ -979,6 +960,14 @@ operator * (const Time& lhs, T rhs) return Time (lhs.m_data * rhs); } +// Leave undocumented +template +typename std::enable_if::value, Time>::type +operator * (const Time& lhs, T rhs) +{ + return lhs * int64x64_t(rhs); +} + /** * Scale a Time by a numeric value. * @@ -999,22 +988,6 @@ operator * (T lhs, const Time& rhs) return rhs * lhs; } -/** - * Scale a Time by a floating point value. - * - * \tparam T Floating point data type (float, double, etc.) - * - * \param [in] lhs The scale value - * \param [in] rhs The Time instance to scale - * \returns A new Time instance containing the scaled value - */ -template -typename std::enable_if::value, Time>::type -operator * (const Time& lhs, T rhs) -{ - return lhs * int64x64_t(rhs); -} - /** * Exact division, returning a dimensionless fixed point number. * @@ -1074,15 +1047,7 @@ operator / (const Time& lhs, T rhs) return Time(lhs.m_data / rhs); } -/** - * Divide a Time by a floating point value. - * - * \tparam T Floating point data type (float, double, etc.) - * - * \param [in] lhs The Time instance to scale - * \param [in] rhs The scale value - * \returns A new Time instance containing the scaled value - */ +// Leave undocumented template typename std::enable_if::value, Time>::type operator / (const Time& lhs, T rhs) @@ -1090,10 +1055,11 @@ operator / (const Time& lhs, T rhs) return lhs / int64x64_t(rhs); } + /** * Remainder (modulus) from the quotient of two Times. * - * This is exactly the same function as Rem() + * Rem() and operator% are equivalent: * * Rem (ta, tb) == ta % tb; * @@ -1101,12 +1067,20 @@ operator / (const Time& lhs, T rhs) * \param [in] lhs The first time value * \param [in] rhs The second time value * \returns The remainder of `lhs / rhs`. + * @{ */ inline Time operator % (const Time & lhs, const Time & rhs) { return Time (lhs.m_data % rhs.m_data); } +inline Time +Rem (const Time & lhs, const Time & rhs) +{ + return Time (lhs.m_data % rhs.m_data); +} +/** @} */ + /** * Integer quotient from dividing two Times. * @@ -1132,24 +1106,6 @@ Div (const Time & lhs, const Time & rhs) { return lhs.m_data / rhs.m_data; } -/** - * Remainder (modulus) from the quotient of two Times. - * - * This is exactly the same function as operator%() - * - * Rem (ta, tb) == ta % tb; - * - * \see Div() - * \param [in] lhs The first time value - * \param [in] rhs The second time value - * \returns The result of the remainder of the first input / second input value. - */ -inline Time -Rem (const Time & lhs, const Time & rhs) -{ - return Time (lhs.m_data % rhs.m_data); -} - /** * Compound addition assignment for Time. * \param [in] lhs The first value diff --git a/src/core/model/pair.h b/src/core/model/pair.h index 0084e2faa..36e60de8f 100644 --- a/src/core/model/pair.h +++ b/src/core/model/pair.h @@ -31,6 +31,14 @@ namespace ns3 { +/** + * Output streamer for a std::pair. + * \tparam A \deduced Type of the `pair.first`. + * \tparam B \deduced Type of the `pair.second`. + * \param [in,out] os The output stream. + * \param [in] p The pair. + * \returns The output stream. + */ template std::ostream & operator << (std::ostream &os, const std::pair &p) @@ -78,10 +86,7 @@ public: * \return stored value as std::pair. */ result_type Get (void) const; - /** - * Set the stored value. - * \param[in] value std::pair to be stored. - */ + /* Documented by print-introspected-doxygen.cc */ void Set (const result_type &value); template @@ -94,6 +99,7 @@ private: class PairChecker : public AttributeChecker { public: + /** Type holding an AttributeChecker for each member of a pair. */ typedef std::pair, Ptr > checker_pair_type; /** @@ -170,13 +176,21 @@ template class PairChecker : public ns3::PairChecker { public: + /** Default c'tor. */ PairChecker (void); + /** + * Construct from a pair of AttributeChecker's. + * \param firstchecker The AttributeChecker for first. + * \param secondchecker The AttributeChecker for second. + */ PairChecker (Ptr firstchecker, Ptr secondchecker); void SetCheckers (Ptr firstchecker, Ptr secondchecker); typename ns3::PairChecker::checker_pair_type GetCheckers (void) const; private: + /** The first checker. */ Ptr m_firstchecker; + /** The second checker. */ Ptr m_secondchecker; }; @@ -334,6 +348,14 @@ PairValue::GetAccessor (T &value) const return true; } +/** + * Create an AttributeAccessor for std::pair<>. + * \tparam A \explicit The type of pair.first. + * \tparam B \explicit The type of pair.second. + * \tparam T1 \deduced The argument pair type. + * \param [in] a1 The std::pair to be accessed. + * \returns The AttributeAccessor. + */ template Ptr MakePairAccessor (T1 a1) { @@ -342,4 +364,4 @@ Ptr MakePairAccessor (T1 a1) } // namespace ns3 -#endif // PAIR_H \ No newline at end of file +#endif // PAIR_H diff --git a/src/core/model/show-progress.h b/src/core/model/show-progress.h index d2e0450c3..a7adcf68d 100644 --- a/src/core/model/show-progress.h +++ b/src/core/model/show-progress.h @@ -165,6 +165,11 @@ private: /** * Show execution progress. * This function actually generates output, when directed by CheckProgress(). + * \param [in] nEvents The actual number of events processed since the last + * progress output. + * \param [in] ratio The current ratio of elapsed wall clock time to the + * target update interval. + * \param [in] speed The execution speed relative to wall clock time. */ void GiveFeedback (uint64_t nEvents, int64x64_t ratio, int64x64_t speed); diff --git a/src/core/model/synchronizer.h b/src/core/model/synchronizer.h index e0e34a46f..04bca0ca1 100644 --- a/src/core/model/synchronizer.h +++ b/src/core/model/synchronizer.h @@ -165,9 +165,11 @@ public: * waiting in the Synchronize method that an event has happened which demands * a reevaluation of the wait time. * + * @param [in] cond The new value for the condition variable. + * * @see Signal */ - void SetCondition (bool); + void SetCondition (bool cond); /** * @brief Ask the synchronizer to remember what time it is. @@ -282,9 +284,10 @@ protected: * waiting in the Synchronize method that an event has happened which * demands a reevaluation of the wait time. * + * @param [in] cond The new value for the condition variable. * @see SetCondition */ - virtual void DoSetCondition (bool) = 0; + virtual void DoSetCondition (bool cond) = 0; /** * @brief Get the drift between the real time clock used to synchronize diff --git a/src/core/model/system-condition.h b/src/core/model/system-condition.h index 7485c8451..a0cb07f3c 100644 --- a/src/core/model/system-condition.h +++ b/src/core/model/system-condition.h @@ -67,6 +67,8 @@ class SystemConditionPrivate; * context and put the processor to sleep until an event happens somewhere * else that */ +// The last two paragraphs are truncated in the earliest commit of this code: +// 2008-07-15 Craig Dowell add system threads and synchronization primitives class SystemCondition { public: diff --git a/src/core/model/time.cc b/src/core/model/time.cc index e7d710eb7..ecc54e83f 100644 --- a/src/core/model/time.cc +++ b/src/core/model/time.cc @@ -61,7 +61,10 @@ namespace { return UNIT_COEFF[u] * std::pow (10L, UNIT_POWER[u]); } - /** Initializer for \c UNIT_VALUE */ + /** + * Initializer for \c UNIT_VALUE + * \returns The array of scale factors between units. + */ long double * InitUnitValue (void) { diff --git a/src/core/model/traced-value.h b/src/core/model/traced-value.h index 024a0ace9..c262a1301 100644 --- a/src/core/model/traced-value.h +++ b/src/core/model/traced-value.h @@ -75,7 +75,7 @@ namespace TracedValueCallback { */ /** * TracedValue Callback signature for POD. - * + * @{ * \param [in] oldValue original value of the traced variable * \param [in] newValue new value of the traced variable */ @@ -89,8 +89,11 @@ typedef void (* Uint32)(uint32_t oldValue, uint32_t newValue); typedef void (* Int64) (int64_t oldValue, int64_t newValue); typedef void (* Uint64)(uint64_t oldValue, uint64_t newValue); typedef void (* Double)(double oldValue, double newValue); +/**@}*/ +/** TracedValue Callback signature for void. */ typedef void (* Void) (void); /**@}*/ + } // namespace TracedValueCallback diff --git a/src/core/model/type-id.cc b/src/core/model/type-id.cc index d1727fa06..b80a79015 100644 --- a/src/core/model/type-id.cc +++ b/src/core/model/type-id.cc @@ -242,7 +242,6 @@ public: * "ns3::" namespace qualifier. * \param [in] supportLevel The support/deprecation status for this attribute. * \param [in] supportMsg Upgrade hint if this attribute is no longer supported. - * \returns This TypeId instance. */ void AddTraceSource (uint16_t uid, std::string name, diff --git a/utils/print-introspected-doxygen.cc b/utils/print-introspected-doxygen.cc index e9a39fb0b..4c7dc3321 100644 --- a/utils/print-introspected-doxygen.cc +++ b/utils/print-introspected-doxygen.cc @@ -1052,7 +1052,7 @@ 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 << "ns3::Attributes by class. " + os << "This is a list of all" << reference << "ns3::Attribute classes. " << "For more information see the" << reference << "ns3:Attributes " << "section of this API documentation and the Attributes sections " << "in the Tutorial and Manual.\n" @@ -1263,7 +1263,7 @@ PrintAllTraceSources (std::ostream & os) * * In doxygen form this will print a comment block with * \verbatim - * \ingroup attribute + * \ingroup attributes * \defgroup attribute_Value Value * \endverbatim * @@ -1279,12 +1279,12 @@ PrintAttributeValueSection (std::ostream & os, NS_LOG_FUNCTION (name); std::string section = "attribute_" + name; - // \ingroup attribute + // \ingroup attributes // \defgroup attribute_Value Attribute - os << commentStart << sectionStart << "attribute\n" + os << commentStart << sectionStart << "attributes\n" << subSectionStart << "attribute_" << name << " " << name << " Attribute\n" - << "Attribute implementation for " << name << "\n"; + << "AttributeValue implementation for " << name << "\n"; if (seeBase) { // Some classes don't live in ns3::. Yuck