--- a/src/core/trace-doc.h Tue Sep 11 12:13:16 2007 +0200
+++ b/src/core/trace-doc.h Tue Sep 11 12:42:37 2007 +0200
@@ -6,39 +6,92 @@
namespace ns3 {
+/**
+ * \brief describe the signature of a trace source
+ */
class TraceDoc
{
typedef std::vector<std::pair<std::string,std::string> > ArgVector;
public:
typedef ArgVector::const_iterator Iterator;
TraceDoc ();
+ /**
+ * \param help a description of the purpose of the trace source
+ */
TraceDoc (std::string help);
+ /**
+ * \param help a description of the purpose of the trace source
+ * \param arg1Type the fully-qualified typename of the first argument of the trace source
+ * \param arg1Help the purpose of the first argument of the trace source
+ */
TraceDoc (std::string help,
- std::string arg0Type,
- std::string arg0Help);
- TraceDoc (std::string help,
- std::string arg0Type,
- std::string arg0Help,
std::string arg1Type,
std::string arg1Help);
+ /**
+ * \param help a description of the purpose of the trace source
+ * \param arg1Type the fully-qualified typename of the first argument of the trace source
+ * \param arg1Help the purpose of the first argument of the trace source
+ * \param arg2Type the fully-qualified typename of the second argument of the trace source
+ * \param arg2Help the purpose of the second argument of the trace source
+ */
TraceDoc (std::string help,
- std::string arg0Type,
- std::string arg0Help,
std::string arg1Type,
std::string arg1Help,
std::string arg2Type,
std::string arg2Help);
+ /**
+ * \param help a description of the purpose of the trace source
+ * \param arg1Type the fully-qualified typename of the first argument of the trace source
+ * \param arg1Help the purpose of the first argument of the trace source
+ * \param arg2Type the fully-qualified typename of the second argument of the trace source
+ * \param arg2Help the purpose of the second argument of the trace source
+ * \param arg3Type the fully-qualified typename of the third argument of the trace source
+ * \param arg3Help the purpose of the third argument of the trace source
+ */
TraceDoc (std::string help,
- std::string arg0Type,
- std::string arg0Help,
std::string arg1Type,
std::string arg1Help,
std::string arg2Type,
std::string arg2Help,
std::string arg3Type,
std::string arg3Help);
+ /**
+ * \param help a description of the purpose of the trace source
+ * \param arg1Type the fully-qualified typename of the first argument of the trace source
+ * \param arg1Help the purpose of the first argument of the trace source
+ * \param arg2Type the fully-qualified typename of the second argument of the trace source
+ * \param arg2Help the purpose of the second argument of the trace source
+ * \param arg3Type the fully-qualified typename of the third argument of the trace source
+ * \param arg3Help the purpose of the third argument of the trace source
+ * \param arg4Type the fully-qualified typename of the fourth argument of the trace source
+ * \param arg4Help the purpose of the fourth argument of the trace source
+ */
+ TraceDoc (std::string help,
+ std::string arg1Type,
+ std::string arg1Help,
+ std::string arg2Type,
+ std::string arg2Help,
+ std::string arg3Type,
+ std::string arg3Help,
+ std::string arg4Type,
+ std::string arg4Help);
+ /**
+ * \returns the help string associated to this trace source
+ */
std::string GetHelp (void) const;
+ /**
+ * \returns an iterator which points to the first descriptor of the trace source.
+ *
+ * Each descriptor is a pair of strings. The first one describes the type of the argument
+ * while the second one describeds the purpose of the argument.
+ */
Iterator ArgsBegin (void) const;
+ /**
+ * \returns an iterator which points to the last descriptor of the trace source.
+ *
+ * Each descriptor is a pair of strings. The first one describes the type of the argument
+ * while the second one describeds the purpose of the argument.
+ */
Iterator ArgsEnd (void) const;
private:
ArgVector m_argVector;
--- a/src/core/trace-resolver.h Tue Sep 11 12:13:16 2007 +0200
+++ b/src/core/trace-resolver.h Tue Sep 11 12:42:37 2007 +0200
@@ -70,13 +70,28 @@
*/
virtual void Disconnect (std::string path, CallbackBase const &cb) = 0;
+ /**
+ * \brief hold a list of trace sources
+ */
class SourceCollection
{
public:
+ /**
+ * \brief describe a single trace source
+ */
struct Source
{
+ /**
+ * The trace path associated to this trace source
+ */
std::string path;
+ /**
+ * The trace context associated to this trace source
+ */
TraceContext context;
+ /**
+ * Document the signature of this trace source
+ */
TraceDoc doc;
};
typedef std::vector<struct Source>::const_iterator Iterator;
@@ -84,7 +99,15 @@
const TraceContext &context,
const TraceDoc &doc);
+ /**
+ * \returns an iterator which points to the first element of the set of
+ * trace sources collected in this SourceCollection object.
+ */
Iterator Begin (void) const;
+ /**
+ * \returns an iterator which points to the last element of the set of
+ * trace sources collected in this SourceCollection object.
+ */
Iterator End (void) const;
private:
typedef std::vector<struct Source> SourceVector;
@@ -101,6 +124,14 @@
virtual void CollectSources (std::string path, const TraceContext &context,
SourceCollection *collection) = 0;
+ /**
+ * \param os the output stream to which ascii output should be written.
+ * \param context the context associated to the current recursive level.
+ *
+ * This method is invoked recursively until each trace source has been
+ * connected to a trace sink which can output an ascii representation
+ * of each trace event on the output stream specified.
+ */
virtual void TraceAll (std::ostream &os, const TraceContext &context) = 0;
protected:
/**
--- a/src/node/node-list.h Tue Sep 11 12:13:16 2007 +0200
+++ b/src/node/node-list.h Tue Sep 11 12:42:37 2007 +0200
@@ -91,6 +91,8 @@
*
* Connect input callback to all trace sources which match
* the input namespace regexp.
+ * A tutorial which explains how to use this method can be
+ * found in the \ref tracing section.
*/
static void Connect (std::string name, const CallbackBase &cb);
/**
@@ -101,9 +103,27 @@
* the input namespace regexp.
*/
static void Disconnect (std::string name, const CallbackBase &cb);
+ /**
+ * \param os the output stream on which the content of each trace event should be
+ * dumped in ascii format.
+ *
+ * Enable _every_ trace source accessible from the NodeList and write to the
+ * output stream an ascii representation of each trace event.
+ * This method is very useful to get quick-and-dirty trace output from a
+ * simulation.
+ * More fancy tracing output could be generated with the ns3::NodeList::Connect
+ * method as explained in the \ref tracing section.
+ */
static void TraceAll (std::ostream &os);
+ /**
+ * \returns the trace resolver used by the ns3::NodeList::Connect,
+ * ns3::NodeList::Disconnect, and, ns3::NodeList::TraceAll methods.
+ *
+ * Using this method directly is not really recommended. Instead, users
+ * should use one of the three methods ns3::NodeList::Connect,
+ * ns3::NodeList::Disconnect, or, ns3::NodeList::TraceAll methods.
+ */
static Ptr<TraceResolver> GetTraceResolver (void);
-private:
};
}//namespace ns3