[Doxygen] Fix errors; fix organization of Callback; organize Time.

2014-08-13 17:17:26 -07:00
parent 2d79be2427
commit 49bf6a544f
5 changed files with 440 additions and 500 deletions
--- a/src/core/model/callback.h
+++ b/src/core/model/callback.h
@@ -32,6 +32,9 @@

 namespace ns3 {

+// Define the doxygen subgroups all at once,
+// since the implementations are interleaved.
+
 /**
 * \ingroup core
 * \defgroup callback Callbacks
@@ -42,19 +45,68 @@ namespace ns3 {
 */
 /**
 * \ingroup callback
+ * \defgroup callbackimpl Callback Implementation
+ * Callback implementation classes
 */
-/**@{*/
 /**
+ * \ingroup callback
+ * \defgroup makecallbackmemptr MakeCallback from member function pointer
+ *
+ * Build Callbacks for class method members which take varying numbers
+ * of arguments and potentially returning a value.
+ *
+ * Generally the \c MakeCallback functions are invoked with the
+ * method function address first, followed by the \c this pointer:
+ * \code
+ *   MakeCallback ( & MyClass::Handler, this);
+ * \endcode
+ *
+ * There is not a version with bound arguments.  You may be able to
+ * get the same result by using \c MakeBoundCallback with a \c static
+ * member function, as in:
+ * \code
+ *   MakeBoundCallback ( & MyClass::StaticHandler, this);
+ * \endcode
+ * This still leaves two argument slots available for binding.
+ */
+/**
+ * \ingroup callback
+ * \defgroup makecallbackfnptr MakeCallback from function pointers
+ *
+ * Build Callbacks for functions which take varying numbers of arguments
+ * and potentially returning a value.
+ */
+/**
+ * \ingroup callback
+ * \defgroup makenullcallback MakeCallback with no arguments
+ *
+ * Define empty (Null) callbacks as placeholders for unset callback variables.
+ */
+/**
+ * \ingroup callback
+ * \defgroup makeboundcallback MakeBoundCallback from functions bound with up to three arguments.
+ *
+ * Build bound Callbacks which take varying numbers of arguments,
+ * and potentially returning a value.
+ *
+ * \internal
+ *
+ * The following is experimental code. It works but we have
+ * not yet determined whether or not it is really useful and whether
+ * or not we really want to use it.
+ */
+
+  
+/**
+ * \ingroup makecallbackmemptr
+ *
 * Trait class to convert a pointer into a reference,
 * used by MemPtrCallBackImpl
+ * @{
 */
 template <typename T>
 struct CallbackTraits;

-/**
- * Trait class to convert a pointer into a reference,
- * used by MemPtrCallBackImpl
- */
 template <typename T>
 struct CallbackTraits<T *>
 {
@@ -69,11 +121,6 @@ struct CallbackTraits<T *>
 };
 /**@}*/

-/**
- * \ingroup callback
- * \defgroup callbackimpl Callback Implementation
- * Callback implementation classes
- */
 /**
 * \ingroup callbackimpl
 * Abstract base class for CallbackImpl
@@ -103,8 +150,9 @@ class CallbackImpl;
 /**
 * \ingroup callbackimpl
 * CallbackImpl classes with varying numbers of argument types
+ *
+ * @{
 */
-/**@{*/
 /** CallbackImpl class with no arguments. */
 template <typename R>
 class CallbackImpl<R,empty,empty,empty,empty,empty,empty,empty,empty,empty> : public CallbackImplBase {
@@ -179,7 +227,7 @@ public:


 /**
- * \ingroup callback
+ * \ingroup callbackimpl
 * CallbackImpl with functors
 */
 template <typename T, typename R, typename T1, typename T2, typename T3, typename T4,typename T5, typename T6, typename T7, typename T8, typename T9>
@@ -325,7 +373,7 @@ private:
 };

 /**
- * \ingroup callback
+ * \ingroup makecallbackmemptr
 * CallbackImpl for pointer to member functions
 */
 template <typename OBJ_PTR, typename MEM_PTR, typename R, typename T1, typename T2, typename T3, typename T4, typename T5, typename T6, typename T7, typename T8, typename T9>
@@ -474,7 +522,7 @@ private:
 };

 /**
- * \ingroup callback
+ * \ingroup callbackimpl
 * CallbackImpl for functors with first argument bound at construction
 */
 template <typename T, typename R, typename TX, typename T1, typename T2, typename T3, typename T4,typename T5, typename T6, typename T7, typename T8>
@@ -608,7 +656,7 @@ private:
 };

 /**
- * \ingroup callback
+ * \ingroup callbackimpl
 * CallbackImpl for functors with first two arguments bound at construction
 */
 template <typename T, typename R, typename TX1, typename TX2, typename T1, typename T2, typename T3, typename T4,typename T5, typename T6, typename T7>
@@ -730,7 +778,7 @@ private:
 };

 /**
- * \ingroup callback
+ * \ingroup callbackimpl
 * CallbackImpl for functors with first three arguments bound at construction
 */
 template <typename T, typename R, typename TX1, typename TX2, typename TX3, typename T1, typename T2, typename T3, typename T4,typename T5, typename T6>
@@ -841,7 +889,7 @@ private:
 };

 /**
- * \ingroup callback
+ * \ingroup callbackimpl
 * Base class for Callback class.
 * Provides pimpl abstraction.
 */
@@ -1219,13 +1267,6 @@ bool operator != (Callback<R,T1,T2,T3,T4,T5,T6,T7,T8,T9> a, Callback<R,T1,T2,T3,
  return !a.IsEqual (b);
 }

-/**
- * \ingroup callback
- * \defgroup makecallbackmemptr MakeCallback from member function pointer
- *
- * Build Callbacks for class method members which take varying numbers of arguments
- * and potentially returning a value.
- */
 /**
 * \ingroup makecallbackmemptr
 * @{
@@ -1320,13 +1361,6 @@ Callback<R,T1,T2,T3,T4,T5,T6,T7,T8,T9> MakeCallback (R (T::*memPtr)(T1,T2,T3,T4,
 }
 /**@}*/

-/**
- * \ingroup callback
- * \defgroup makecallbackfnptr MakeCallback from function pointers
- *
- * Build Callbacks for functions which take varying numbers of arguments
- * and potentially returning a value.
- */
 /**
 * \ingroup makecallbackfnptr
 * @{
@@ -1380,10 +1414,6 @@ Callback<R,T1,T2,T3,T4,T5,T6,T7,T8,T9> MakeCallback (R (*fnPtr)(T1,T2,T3,T4,T5,T
 }
 /**@}*/

-/**
- * \ingroup callback
- * \defgroup makenullcallback MakeCallback with no arguments
- */
 /**
 * \ingroup makenullcallback
 * @{
@@ -1438,27 +1468,10 @@ Callback<R,T1,T2,T3,T4,T5,T6,T7,T8,T9> MakeNullCallback (void) {
 /**@}*/


-/**
- * \ingroup callback
- * \defgroup makeboundcallback MakeBoundCallback from functions bound with up to three arguments.
- */
-  
 /**
 * \ingroup makeboundcallback
- *
- * Build bound Callbacks which take varying numbers of arguments,
- * and potentially returning a value.
- *
- * \internal
- *
- * The following is experimental code. It works but we have
- * not yet determined whether or not it is really useful and whether
- * or not we really want to use it.
- *
- * @{
- */
-/**
 * @{
+ * Make Callbacks with one bound argument.
 * \param fnPtr function pointer
 * \param a1 first bound argument
 * \return a bound Callback
@@ -1528,11 +1541,13 @@ Callback<R,T1,T2,T3,T4,T5,T6,T7,T8> MakeBoundCallback (R (*fnPtr)(TX,T1,T2,T3,T4
 /**@}*/

 /**
+ * \ingroup makeboundcallback
+ * @{
+ * Make Callbacks with two bound arguments.
 * \param fnPtr function pointer
 * \param a1 first bound argument
 * \param a2 second bound argument 
 * \return a bound Callback
- * @{
 */
 template <typename R, typename TX1, typename TX2, typename ARG1, typename ARG2>
 Callback<R> MakeBoundCallback (R (*fnPtr)(TX1,TX2), ARG1 a1, ARG2 a2) {
@@ -1592,12 +1607,14 @@ Callback<R,T1,T2,T3,T4,T5,T6,T7> MakeBoundCallback (R (*fnPtr)(TX1,TX2,T1,T2,T3,
 /**@}*/

 /**
+ * \ingroup makeboundcallback
+ * @{
+ * Make Callbacks with three bound arguments.
 * \param a1 first bound argument
 * \param a2 second bound argument 
 * \param a3 third bound argument 
 * \param fnPtr function pointer
 * \return a bound Callback
- * @{
 */
 template <typename R, typename TX1, typename TX2, typename TX3, typename ARG1, typename ARG2, typename ARG3>
 Callback<R> MakeBoundCallback (R (*fnPtr)(TX1,TX2,TX3), ARG1 a1, ARG2 a2, ARG3 a3) {
@@ -1649,7 +1666,6 @@ Callback<R,T1,T2,T3,T4,T5,T6> MakeBoundCallback (R (*fnPtr)(TX1,TX2,TX3,T1,T2,T3
 }
 /**@}*/

-/**@}*/

 } // namespace ns3

--- a/src/core/model/nstime.h
+++ b/src/core/model/nstime.h
--- a/src/core/model/time.cc
+++ b/src/core/model/time.cc
@@ -44,6 +44,8 @@ Time::MarkedTimes * Time::g_markingTimes = 0;
 * \internal
 * Get mutex for critical sections around modification of Time::g_markingTimes
 *
+ * \returns The static mutex to control access to Time::g_markingTimes.
+ *
 * \relates Time
 */
 SystemMutex &
@@ -387,8 +389,8 @@ Time::As (const enum Unit unit) const
 }
 

-std::ostream&
-operator<< (std::ostream& os, const Time & time)
+std::ostream &
+operator << (std::ostream & os, const Time & time)
 {
  os << time.As (Time::GetResolution ());
  return os;
@@ -427,7 +429,8 @@ operator << (std::ostream & os, const TimeWithUnit & timeU)
 }


-std::istream& operator>> (std::istream& is, Time & time)
+std::istream &
+operator >> (std::istream & is, Time & time)
 {
  std::string value;
  is >> value;
--- a/src/flow-monitor/model/histogram.h
+++ b/src/flow-monitor/model/histogram.h
@@ -38,7 +38,7 @@ namespace ns3 {
 *
 * \todo Add support for negative data.
 *
- * \todo Add method(s) to estimate \f$N\f$, \f$\mu\f$, and \f$s^2\f$ from the histogram,
+ * \todo Add method(s) to estimate parameters from the histogram,
 * see http://www.dspguide.com/ch2/4.htm
 *
 */
--- a/src/internet/model/ripng.h
+++ b/src/internet/model/ripng.h
@@ -36,7 +36,7 @@ namespace ns3 {
 /**
 * \defgroup ripng RIPng
 *
- * The RIPng protocol (\rfc{2080}) is a unicast-only IPv6 IGP (Interior Gateway Protocol).
+ * The RIPng protocol (\RFC{2080}) is a unicast-only IPv6 IGP (Interior Gateway Protocol).
 * Its convergence time is rather long. As a consequence, it is suggested to
 * carefully check the network topology and the route status before sending
 * data flows.
@@ -168,7 +168,7 @@ std::ostream& operator<< (std::ostream& os, RipNgRoutingTableEntry const& route)
 /**
 * \ingroup ripng
 *
- * \brief RIPng Routing Protocol, defined in \rfc{2080}.
+ * \brief RIPng Routing Protocol, defined in \RFC{2080}.
 */
 class RipNg : public Ipv6RoutingProtocol
 {