From 42ea8aabe07ff2d54f96f6ce09c555baae5285f7 Mon Sep 17 00:00:00 2001
From: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Date: Tue, 13 Feb 2007 10:23:47 +0100
Subject: [PATCH] add API doc

---
 src/core/debug.h | 98 ++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 95 insertions(+), 3 deletions(-)

diff --git a/src/core/debug.h b/src/core/debug.h
index 458d1f243..d1aecbb18 100644
--- a/src/core/debug.h
+++ b/src/core/debug.h
@@ -24,10 +24,53 @@
 #include <string>
 #include <iostream>
 
+/**
+ * \defgroup debugging
+ * \brief Debugging functions and macros
+ *
+ * The ns3 debugging support provides a few simple macros
+ * for debugging and sending out messages to the user. There
+ * two classes of functionality:
+ *   - ASSERT functionality: macros which are used to verify
+ *     at runtime that a certain condition is true. If it is
+ *     not true, the program halts. These checks are built
+ *     into the program only in debugging builds. They are
+ *     removed in optimized builds.
+ *
+ *   - DEBUG functionality: macros which allow developers to
+ *     send information out on screen only in debugging builds.
+ *     All debug messages are disabled by default. To enable 
+ *     selected debug messages, use the ns3::DebugComponentEnable
+ *     function. Alternatively, you can use the NS3_DEBUG 
+ *     environment variable to define a ';'-separated list of
+ *     messages to enable. For example, NS3_DEBUG=a;b;c;DAFD;GH
+ *     would enable the components 'a', 'b', 'c', 'DAFD', and, 'GH'.
+ */
+
 namespace ns3 {
 
+/**
+ * \param name a debug component name
+ * \ingroup debugging
+ *
+ * Enable the debugging output associated with that debug component.
+ * The debugging output can be later disabled with a call
+ * to ns3::DebugComponentDisable.
+ */
 void DebugComponentEnable (char const *name);
+/**
+ * \param name a debug component name
+ * \ingroup debugging
+ *
+ * Disable the debugging output associated with that debug component.
+ * The debugging output can be later re-enabled with a call
+ * to ns3::DebugComponentEnable.
+ */
 void DebugComponentDisable (char const *name);
+/**
+ * \ingroup debugging
+ * Print the list of debugging messages available.
+ */
 void DebugComponentPrintList (void);
 
 class DebugComponent {
@@ -40,6 +83,15 @@ private:
   bool m_isEnabled;
 };
 
+/**
+ * \ingroup debugging
+ *
+ * When an NS3_ASSERT cannot verify its condition, 
+ * this function is called. This is where you should
+ * be able to put a breakpoint with a debugger if
+ * you want to catch assertions before the program 
+ * halts.
+ */
 void AssertBreakpoint (void);
 
 }; // namespace ns3
@@ -47,15 +99,46 @@ void AssertBreakpoint (void);
 
 #ifdef NS3_DEBUG_ENABLE
 
+/**
+ * \ingroup debugging
+ * \param name a string
+ *
+ * Define a Debug component with a specific name. This macro
+ * should be used at the top of every file in which you want 
+ * to use the NS3_DEBUG macro. This macro defines a new
+ * "debug component" which can be later selectively enabled
+ * or disabled with the ns3::DebugComponentEnable and 
+ * ns3::DebugComponentDisable functions or with the NS3_DEBUG
+ * environment variable.
+ */
 #define NS3_DEBUG_COMPONENT_DEFINE(name)                                \
   static ns3::DebugComponent g_debug = ns3::DebugComponent (name);
 
-#define NS3_DEBUG(x)				\
+/**
+ * \ingroup debugging
+ * \param msg message to output
+ *
+ * Generate debugging output in the "debug component" of the 
+ * current file. i.e., every call to NS3_DEBUG from within
+ * a file implicitely generates out within the component
+ * defined with the NS3_DEBUG_COMPONENT_DEFINE macro in the
+ * same file.
+ */
+#define NS3_DEBUG(msg)				\
   if (g_debug.IsEnabled ())			\
     {						\
-      std::cout << x << std::endl;		\
+      std::cout << msg << std::endl;		\
     }
 
+/**
+ * \ingroup debugging
+ * \param condition condition to verifiy.
+ *
+ * At runtime, in debugging builds, if this condition is not
+ * true, the program prints the source file, line number and 
+ * unverified condition and halts in the ns3::AssertBreakpoint 
+ * function.
+ */
 #define NS3_ASSERT(condition)                                   \
   if (!(condition))                                             \
     {                                                           \
@@ -65,6 +148,15 @@ void AssertBreakpoint (void);
       ns3::AssertBreakpoint ();                                 \
     }
 
+/**
+ * \ingroup debugging
+ * \param condition condition to verifiy.
+ * \param message message to output
+ *
+ * At runtime, in debugging builds, if this condition is not
+ * true, the program prints the message to output and
+ * halts in the ns3::AssertBreakpoint function.
+ */
 #define NS3_ASSERT_MSG(condition, message) \
   if (!(condition))                        \
     {                                      \
@@ -77,7 +169,7 @@ void AssertBreakpoint (void);
 #define NS3_DEBUG_COMPONENT_DEFINE(name)
 #define NS3_DEBUG(x)
 #define NS3_ASSERT(cond)
-#define NS3_ASSERT_MSG(cond)
+#define NS3_ASSERT_MSG(cond,msg)
 
 #endif /* NS3_DEBUG_ENABLE */