From 52d60ea049aabf52e33c38f6eaf2a798d820ab93 Mon Sep 17 00:00:00 2001
From: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
Date: Sun, 13 May 2007 11:46:11 +0200
Subject: [PATCH] add dox documentation for Node

---
 src/node/node.cc |   6 ---
 src/node/node.h  | 105 +++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 101 insertions(+), 10 deletions(-)

diff --git a/src/node/node.cc b/src/node/node.cc
index a4f5cf693..ca8871080 100644
--- a/src/node/node.cc
+++ b/src/node/node.cc
@@ -69,12 +69,6 @@ Node::GetSystemId (void) const
   return m_sid;
 }
 
-void   
-Node::SetSystemId(uint32_t s )
-{
-  m_sid = s;
-}
-
 uint32_t 
 Node::AddDevice (Ptr<NetDevice> device)
 {
diff --git a/src/node/node.h b/src/node/node.h
index d2e63cad6..d8d5ffecc 100644
--- a/src/node/node.h
+++ b/src/node/node.h
@@ -36,33 +36,130 @@ class TraceResolver;
 class NetDevice;
 class Application;
 
+/**
+ * \brief A network Node.
+ *
+ * This class holds together:
+ *   - a list of NetDevice objects which represent the network interfaces
+ *     of this node which are connected to other Node instances through
+ *     Channel instances.
+ *   - a list of Application objects which represent the userspace
+ *     traffic generation applications which interact with the Node
+ *     through the Socket API.
+ *   - a node Id: a unique per-node identifier.
+ *   - a system Id: a unique Id used for parallel simulations.
+ *   - a trace resolver which can be used to connect user trace sinks
+ *     to the node's trace sources.
+ *
+ * Every Node created is added to the NodeList automatically.
+ */
 class Node : public Interface
 {
 public:
   static const InterfaceId iid;
 
-  Node();
-  Node(uint32_t); // Specify which system for a distributed simulation
   virtual ~Node();
 
+  /**
+   * \param context the trace context for the TraceResolver to create
+   * \returns a newly-created TraceResolver. The caller takes
+   *          ownership of the returned pointer.
+   *
+   * Request the Node to create a trace resolver. This method
+   * could be used directly by a user who needs access to very low-level
+   * trace configuration.
+   */
   TraceResolver *CreateTraceResolver (TraceContext const &context);
 
+  /**
+   * \returns the unique id of this node.
+   * 
+   * This unique id happens to be also the index of the Node into
+   * the NodeList. 
+   */
   uint32_t GetId (void) const;
-  uint32_t GetSystemId (void) const;
-  void SetSystemId(uint32_t s);
 
+  /**
+   * \returns the system id for parallel simulations associated
+   *          to this node.
+   */
+  uint32_t GetSystemId (void) const;
+
+  /**
+   * \param device NetDevice to associate to this node.
+   * \returns the index of the NetDevice into the Node's list of
+   *          NetDevice.
+   *
+   * Associate this device to this node.
+   * This method is called automatically from NetDevice::NetDevice
+   * so the user has little reason to call this method himself.
+   */
   uint32_t AddDevice (Ptr<NetDevice> device);
+  /**
+   * \param index the index of the requested NetDevice
+   * \returns the requested NetDevice associated to this Node.
+   */
   Ptr<NetDevice> GetDevice (uint32_t index) const;
+  /**
+   * \returns the number of NetDevice instances associated
+   *          to this Node.
+   */
   uint32_t GetNDevices (void) const;
 
+  /**
+   * \param application Application to associate to this node.
+   * \returns the index of the Application within the Node's list
+   *          of Application.
+   *
+   * Associated this Application to this Node. This method is called
+   * automatically from Application::Application so the user
+   * has little reasons to call this method directly.
+   */
   uint32_t AddApplication (Ptr<Application> application);
+  /**
+   * \param index
+   * \returns the application associated to this requested index
+   *          within this Node.
+   */
   Ptr<Application> GetApplication (uint32_t index) const;
+  /**
+   * \returns the number of applications associated to this Node.
+   */
   uint32_t GetNApplications (void) const;
 
 protected:
+  /**
+   * Must be invoked by subclasses only.
+   */
+  Node();
+  /**
+   * \param systemId a unique integer used for parallel simulations.
+   *
+   * Must be invoked by subclasses only.
+   */
+  Node(uint32_t systemId);
+  /**
+   * The dispose method. Subclasses must override this method
+   * and must chain up to it by calling Node::DoDispose at the
+   * end of their own DoDispose method.
+   */
   virtual void DoDispose (void);
 private:
+  /**
+   * \param context the trace context
+   * \returns a trace resolver to the user. The user must delete it.
+   *
+   * Subclasses must implement this method.
+   */
   virtual TraceResolver *DoCreateTraceResolver (TraceContext const &context) = 0;
+  /**
+   * \param device the device added to this Node.
+   *
+   * This method is invoked whenever a user calls Node::AddDevice.
+   * Subclasses are expected to call NetDevice::SetReceiveCallback
+   * at this point to setup the node's receive function for
+   * the NetDevice packets.
+   */
   virtual void DoAddDevice (Ptr<NetDevice> device) const = 0;
 
   uint32_t    m_id;         // Node id for this node