document trace source signatures
authorMathieu Lacage <mathieu.lacage@sophia.inria.fr>
Tue, 28 Aug 2007 13:10:18 +0200
changeset 1379 f323d2dcdaf6
parent 1378 69391eb72cb3
child 1380 799617173a45
document trace source signatures
src/core/composite-trace-resolver.cc
src/core/composite-trace-resolver.h
src/core/object.cc
src/core/trace-doc.cc
src/core/trace-doc.h
src/core/trace-resolver.cc
src/core/trace-resolver.h
src/devices/csma/csma-net-device.cc
src/devices/point-to-point/point-to-point-net-device.cc
src/internet-node/ipv4-l3-protocol.cc
src/mobility/mobility-model-notifier.cc
src/node/queue.cc
--- a/src/core/composite-trace-resolver.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/composite-trace-resolver.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -73,15 +73,15 @@
 
 void 
 CompositeTraceResolver::AddSource (std::string name,
-                                   std::string helpText,
+                                   const TraceDoc &doc,
                                    TraceSource &trace)
 {
-  DoAddSource (name, helpText, trace, TraceContext ());
+  DoAddSource (name, doc, trace, TraceContext ());
 }
 
 void 
 CompositeTraceResolver::DoAddSource (std::string name,
-                                     std::string helpText,
+                                     const TraceDoc &doc,
                                      TraceSource &trace, 
                                      const TraceContext &context)
 {
@@ -99,16 +99,15 @@
       path.append (this->name);
       TraceContext ctx = context;
       ctx.Union (this->context);
-      // XXX help string
-      collection->AddUnique (path, ctx, helpText);
+      collection->AddUnique (path, ctx, this->doc);
     }
     TraceSource *trace;
-    std::string helpText;
+    TraceDoc doc;
   } *item = new SourceCompositeItem ();
   item->name = name;
   item->context = context;
   item->trace = &trace;
-  item->helpText = helpText;
+  item->doc = doc;
   AddItem (item);
 }
 
@@ -401,7 +400,7 @@
 CompositeTraceResolverTest::CreateSubResolver (void)
 {
   Ptr<CompositeTraceResolver> subresolver = Create<CompositeTraceResolver> ();
-  subresolver->AddSource ("trace-int", "test source", m_traceInt, 
+  subresolver->AddSource ("trace-int", TraceDoc ("test source"), m_traceInt, 
                           SubTraceSourceTest (SubTraceSourceTest::INT));
   return subresolver;
 }
@@ -416,9 +415,9 @@
 
   CompositeTraceResolver resolver;
 
-  resolver.AddSource ("trace-double-a", "test source", traceDoubleA, 
+  resolver.AddSource ("trace-double-a", TraceDoc ("test source"), traceDoubleA, 
                       TraceSourceTest (TraceSourceTest::DOUBLEA));
-  resolver.AddSource ("trace-double-b", "test source", traceDoubleB, 
+  resolver.AddSource ("trace-double-b", TraceDoc ("test source"), traceDoubleB, 
                       TraceSourceTest (TraceSourceTest::DOUBLEB));
 
   resolver.Connect ("/*", MakeCallback (&CompositeTraceResolverTest::TraceDouble, this), TraceContext ());
@@ -551,7 +550,7 @@
 
   SVTraceSource<uint16_t> source;
 
-  resolver.AddSource ("uint16_t", "test source", source, TraceSourceTest (TraceSourceTest::UINT16_T));
+  resolver.AddSource ("uint16_t", TraceDoc ("test source"), source, TraceSourceTest (TraceSourceTest::UINT16_T));
   
 
   return ok;
--- a/src/core/composite-trace-resolver.h	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/composite-trace-resolver.h	Tue Aug 28 13:10:18 2007 +0200
@@ -30,6 +30,7 @@
 #include "sv-trace-source.h"
 #include "fv-trace-source.h"
 #include "array-trace-resolver.h"
+#include "trace-doc.h"
 
 namespace ns3 {
 
@@ -53,7 +54,7 @@
    * be automatically extended to contain the input context.
    */
   template <typename T>
-  void AddSource (std::string name, std::string helpText,
+  void AddSource (std::string name, const TraceDoc &doc,
                   TraceSource &trace, T const &context);
   /**
    * \param name name of trace source
@@ -64,7 +65,7 @@
    * resolution.
    */
   void AddSource (std::string name,
-                  std::string helpText,
+                  const TraceDoc &doc,
                   TraceSource &trace);
 
   void AddChild (std::string name, Ptr<Object> child);
@@ -114,7 +115,7 @@
                                       const Operation &operation);
   void DoAddChild (std::string name, Ptr<Object> child, const TraceContext &context);
   void DoAddSource (std::string name,
-                    std::string helpText,
+                    const TraceDoc &doc,
                     TraceSource &trace,
                     const TraceContext &context);
   void Add (std::string name, 
@@ -134,13 +135,13 @@
 template <typename T>
 void 
 CompositeTraceResolver::AddSource (std::string name,
-                                   std::string helpText,
+                                   const TraceDoc &doc,
                                    TraceSource &trace, 
                                    T const &context)
 {
   TraceContext ctx;
   ctx.AddElement (context);
-  DoAddSource (name, helpText, trace, ctx);  
+  DoAddSource (name, doc, trace, ctx);  
 }
 
 template <typename ITERATOR, typename INDEX>
--- a/src/core/object.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/object.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -360,7 +360,7 @@
   {
     ns3::Ptr<ns3::CompositeTraceResolver> resolver = 
       ns3::Create<ns3::CompositeTraceResolver> ();
-    resolver->AddSource ("basea-x", "test source", m_source);
+    resolver->AddSource ("basea-x", ns3::TraceDoc ("test source"), m_source);
     resolver->SetParent (Object::GetTraceResolver ());
     return resolver;
   }
@@ -384,7 +384,7 @@
   {
     ns3::Ptr<ns3::CompositeTraceResolver> resolver = 
       ns3::Create<ns3::CompositeTraceResolver> ();
-    resolver->AddSource ("deriveda-x", "test source", m_sourceDerived);
+    resolver->AddSource ("deriveda-x", ns3::TraceDoc ("test source"), m_sourceDerived);
     resolver->SetParent (BaseA::GetTraceResolver ());
     return resolver;
   }
@@ -411,7 +411,7 @@
   {
     ns3::Ptr<ns3::CompositeTraceResolver> resolver = 
       ns3::Create<ns3::CompositeTraceResolver> ();
-    resolver->AddSource ("baseb-x", "test source", m_source);
+    resolver->AddSource ("baseb-x", ns3::TraceDoc ("test source"), m_source);
     resolver->SetParent (Object::GetTraceResolver ());
     return resolver;
   }
@@ -435,7 +435,7 @@
   {
     ns3::Ptr<ns3::CompositeTraceResolver> resolver = 
       ns3::Create<ns3::CompositeTraceResolver> ();
-    resolver->AddSource ("derivedb-x", "test source", m_sourceDerived);
+    resolver->AddSource ("derivedb-x", ns3::TraceDoc ("test source"), m_sourceDerived);
     resolver->SetParent (BaseB::GetTraceResolver ());
     return resolver;
   }
--- a/src/core/trace-doc.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/trace-doc.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -2,6 +2,10 @@
 
 namespace ns3 {
 
+TraceDoc::TraceDoc ()
+  : m_help ("empty help")
+{}
+
 TraceDoc::TraceDoc (std::string help)
   : m_help (help)
 {}
@@ -17,6 +21,7 @@
 		    std::string arg0Help,
 		    std::string arg1Type,
 		    std::string arg1Help)
+  : m_help (help)
 {
   m_argVector.push_back (std::make_pair (arg0Type, arg0Help));
   m_argVector.push_back (std::make_pair (arg1Type, arg1Help));
@@ -28,6 +33,7 @@
 		    std::string arg1Help,
 		    std::string arg2Type,
 		    std::string arg2Help)
+  : m_help (help)
 {
   m_argVector.push_back (std::make_pair (arg0Type, arg0Help));
   m_argVector.push_back (std::make_pair (arg1Type, arg1Help));
@@ -42,6 +48,7 @@
 		    std::string arg2Help,
 		    std::string arg3Type,
 		    std::string arg3Help)
+  : m_help (help)
 {
   m_argVector.push_back (std::make_pair (arg0Type, arg0Help));
   m_argVector.push_back (std::make_pair (arg1Type, arg1Help));
@@ -49,7 +56,7 @@
   m_argVector.push_back (std::make_pair (arg3Type, arg3Help));
 }
 std::string 
-TraceDoc::GetHelp (void)
+TraceDoc::GetHelp (void) const
 {
   return m_help;
 }
--- a/src/core/trace-doc.h	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/trace-doc.h	Tue Aug 28 13:10:18 2007 +0200
@@ -11,7 +11,7 @@
   typedef std::vector<std::pair<std::string,std::string> > ArgVector;
 public:
   typedef ArgVector::const_iterator Iterator;
-
+  TraceDoc ();
   TraceDoc (std::string help);
   TraceDoc (std::string help,
 	    std::string arg0Type,
@@ -37,7 +37,7 @@
 	    std::string arg2Help,
 	    std::string arg3Type,
 	    std::string arg3Help);
-  std::string GetHelp (void);
+  std::string GetHelp (void) const;
   Iterator ArgsBegin (void) const;
   Iterator ArgsEnd (void) const;
 private:
--- a/src/core/trace-resolver.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/trace-resolver.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -76,13 +76,13 @@
 }
 
 void 
-TraceResolver::SourceCollection::AddUnique (std::string path, const TraceContext &context,
-                                            std::string help)
+TraceResolver::SourceCollection::AddUnique (std::string path, 
+                                            const TraceContext &context,
+                                            const TraceDoc &doc)
 {
   for (SourceVector::const_iterator i = m_sources.begin (); i != m_sources.end (); i++)
     {
       if (i->path == path &&
-          i->help == help &&
           context.IsSimilar (i->context))
         {
           return;
@@ -91,7 +91,7 @@
   struct Source source;
   source.path = path;
   source.context = context;
-  source.help = help;
+  source.doc = doc;
   m_sources.push_back (source);
 }
 void 
@@ -103,7 +103,14 @@
       os << "TraceContext=[";
       i->context.PrintAvailable (os, ",");
       os << "]" << std::endl;
-      os << "help=\"" << i->help << "\"" << std::endl;
+      os << "help=\"" << i->doc.GetHelp () << "\"" << std::endl;
+      os << "const TraceContext &: the trace context associated to the connected trace source." << std::endl;
+      uint32_t k = 0;
+      for (TraceDoc::Iterator j = i->doc.ArgsBegin (); j != i->doc.ArgsEnd (); j++)
+        {
+          os << "argument " << k << "  --  " << j->first << ": " << j->second << "." << std::endl;
+          k++;
+        }
       os << std::endl;
     }
 }
--- a/src/core/trace-resolver.h	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/core/trace-resolver.h	Tue Aug 28 13:10:18 2007 +0200
@@ -24,6 +24,7 @@
 #include <string>
 #include <list>
 #include "trace-context.h"
+#include "trace-doc.h"
 
 namespace ns3 {
 
@@ -74,14 +75,15 @@
   {
   public:
     void Print (std::ostream &os) const;
-    void AddUnique (std::string path, const TraceContext &context,
-                    std::string help);
+    void AddUnique (std::string path, 
+                    const TraceContext &context,
+                    const TraceDoc &doc);
   private:
     struct Source
     {
       std::string path;
       TraceContext context;
-      std::string help;
+      TraceDoc doc;
     };
     typedef std::vector<struct Source> SourceVector;
     SourceVector m_sources;
--- a/src/devices/csma/csma-net-device.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/devices/csma/csma-net-device.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -463,11 +463,13 @@
   Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
   resolver->AddChild ("queue", m_queue);
   resolver->AddSource ("rx",
-                       "receive MAC packet",
+                       TraceDoc ("receive MAC packet",
+                                 "const Packet &", "packet received"),
                        m_rxTrace,
                        CsmaTraceType (CsmaTraceType::RX));
   resolver->AddSource ("drop",
-                       "drop MAC packet",  
+                       TraceDoc ("drop MAC packet",
+                                 "const Packet &", "packet dropped"),
                        m_dropTrace,
                        CsmaTraceType (CsmaTraceType::DROP));
   resolver->SetParent (NetDevice::GetTraceResolver ());
--- a/src/devices/point-to-point/point-to-point-net-device.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/devices/point-to-point/point-to-point-net-device.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -200,7 +200,8 @@
   Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
   resolver->AddChild ("queue", m_queue);
   resolver->AddSource ("rx",
-                       "receive MAC packet",
+                       TraceDoc ("receive MAC packet",
+                                 "const Packet &", "packet received"),
                        m_rxTrace,
                        PointToPointTraceType ());
   resolver->SetParent (NetDevice::GetTraceResolver ());
--- a/src/internet-node/ipv4-l3-protocol.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/internet-node/ipv4-l3-protocol.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -162,11 +162,19 @@
 Ipv4L3Protocol::GetTraceResolver (void)
 {
   Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
-  resolver->AddSource ("tx", "send ipv4 packet to outgoing interface",
+  resolver->AddSource ("tx", 
+                       TraceDoc ("send ipv4 packet to outgoing interface",
+                                 "const Packet &", "packet sent",
+                                 "uint32_t", "index of output ipv4 interface"),
                        m_txTrace, Ipv4L3ProtocolTraceContextElement(Ipv4L3ProtocolTraceContextElement::TX));
-  resolver->AddSource ("rx", "receive ipv4 packet from incoming interface",
+  resolver->AddSource ("rx",
+                       TraceDoc ("receive ipv4 packet from incoming interface",
+                                 "const Packet &", "packet received",
+                                 "uint32_t", "index of input ipv4 interface"),
                        m_rxTrace, Ipv4L3ProtocolTraceContextElement(Ipv4L3ProtocolTraceContextElement::RX));
-  resolver->AddSource ("drop", "drop ipv4 packet",
+  resolver->AddSource ("drop", 
+                       TraceDoc ("drop ipv4 packet",
+                                 "const Packet &", "packet dropped"),
                        m_dropTrace, Ipv4L3ProtocolTraceContextElement (Ipv4L3ProtocolTraceContextElement::DROP));
   resolver->AddArray ("interfaces", 
                       m_interfaces.begin (), m_interfaces.end (), 
--- a/src/mobility/mobility-model-notifier.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/mobility/mobility-model-notifier.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -20,6 +20,7 @@
  */
 #include "mobility-model-notifier.h"
 #include "ns3/composite-trace-resolver.h"
+#include "ns3/trace-doc.h"
 
 namespace ns3 {
 
@@ -44,7 +45,10 @@
 {
   Ptr<CompositeTraceResolver> resolver = 
     Create<CompositeTraceResolver> ();
-  resolver->AddSource ("course-change", "speed vector changed value",
+  resolver->AddSource ("course-change", 
+                       TraceDoc ("The value of the speed vector changed",
+                                 "Ptr<const MobilityModel>", 
+                                 "the mobility model whose course changed"),
                        m_trace);
   resolver->SetParent (Object::GetTraceResolver ());
   return resolver;
--- a/src/node/queue.cc	Tue Aug 28 12:42:27 2007 +0200
+++ b/src/node/queue.cc	Tue Aug 28 13:10:18 2007 +0200
@@ -103,11 +103,17 @@
 Queue::GetTraceResolver (void)
 {
   Ptr<CompositeTraceResolver> resolver = Create<CompositeTraceResolver> ();
-  resolver->AddSource ("enqueue", "store packet in queue",
+  resolver->AddSource ("enqueue", 
+                       TraceDoc ("store packet in queue",
+                                 "const Packet &", "packet queued"),
                        m_traceEnqueue, QueueTraceType (QueueTraceType::ENQUEUE));
-  resolver->AddSource ("dequeue", "remove packet from queue",  
+  resolver->AddSource ("dequeue", 
+                       TraceDoc ("remove packet from queue",
+                                 "const Packet &", "packet dequeued"),
                        m_traceDequeue, QueueTraceType (QueueTraceType::DEQUEUE));
-  resolver->AddSource ("drop", "drop packet from queue", 
+  resolver->AddSource ("drop", 
+                       TraceDoc ("drop packet from queue", 
+                                 "const Packet &", "packet dropped"),
                        m_traceDrop, QueueTraceType (QueueTraceType::DROP));
   resolver->SetParent (Object::GetTraceResolver ());
   return resolver;