From 4f45471b7178a39db3bb03d8186cd7964ba3b229 Mon Sep 17 00:00:00 2001 From: Craig Dowell Date: Sun, 4 Oct 2009 21:46:30 -0700 Subject: [PATCH] Piles o' doxygen --- src/helper/application-container.h | 19 ++- src/helper/ipv4-list-routing-helper.h | 4 +- src/helper/ipv4-static-routing-helper.h | 1 - src/helper/ipv6-list-routing-helper.h | 20 +++ src/helper/ipv6-routing-helper.h | 5 + src/helper/ipv6-static-routing-helper.h | 35 ++++- src/helper/mesh-helper.h | 25 ++- src/helper/mobility-helper.h | 12 ++ src/helper/net-device-container.h | 114 ++++++++++++-- src/helper/node-container.h | 194 +++++++++++++++++++++--- 10 files changed, 377 insertions(+), 52 deletions(-) diff --git a/src/helper/application-container.h b/src/helper/application-container.h index a07d0b21c..a2cebe6ae 100644 --- a/src/helper/application-container.h +++ b/src/helper/application-container.h @@ -37,7 +37,6 @@ namespace ns3 { * add a Ptr to that application into a Container for use * by the caller. This is that container used to hold the Ptr * which are instantiated by the Application helper. - * */ class ApplicationContainer { @@ -52,16 +51,16 @@ public: * been previously instantiated. The single application is specified * by a smart pointer. * - * \param application The application to add to the container. + * \param application The Ptr to add to the container. */ ApplicationContainer (Ptr application); /** * Create an ApplicationContainer with exactly one application which has - * been previously instantiated and assigned a name using the Object name - * service. This Application is specified by its assigned name. + * been previously instantiated and assigned a name using the Object Name + * Service. This Application is then specified by its assigned name. * - * \param name The name of the application object to add to the container. + * \param name The name of the Application Object to add to the container. */ ApplicationContainer (std::string name); @@ -89,7 +88,7 @@ public: Iterator Begin (void) const; /** - * \brief Get an iterator which indicates to the last Application in the + * \brief Get an iterator which indicates past-the-last Application in the * container. * * Applications can be retrieved from the container in two ways. First, @@ -141,10 +140,10 @@ public: * indexed Ptr. * * \code - * uint32_t nApplications = continer.GetN (); + * uint32_t nApplications = container.GetN (); * for (uint32_t i = 0 i < nApplications; ++i) * { - * Ptr p = continer.Get (i) + * Ptr p = container.Get (i) * i->method (); // some Application method * } * \endcode @@ -163,7 +162,7 @@ public: void Add (ApplicationContainer other); /** - * \brief Append the single Ptr to this container. + * \brief Append a single Ptr to this container. * * \param application The Ptr to append. */ @@ -173,7 +172,7 @@ public: * \brief Append to this container the single Ptr referred to * via its object name service registered name. * - * \param name The name of the application object to add to the container. + * \param name The name of the Application Object to add to the container. */ void Add (std::string name); diff --git a/src/helper/ipv4-list-routing-helper.h b/src/helper/ipv4-list-routing-helper.h index f01f82edc..feb405c40 100644 --- a/src/helper/ipv4-list-routing-helper.h +++ b/src/helper/ipv4-list-routing-helper.h @@ -42,8 +42,8 @@ public: Ipv4ListRoutingHelper (); /* - * Construct an Ipv4ListRoutingHelper used to make installing routing - * protocols easier. + * \internal + * Destroy an Ipv4ListRoutingHelper. */ virtual ~Ipv4ListRoutingHelper (); diff --git a/src/helper/ipv4-static-routing-helper.h b/src/helper/ipv4-static-routing-helper.h index 1c00ccb47..6ce21f512 100644 --- a/src/helper/ipv4-static-routing-helper.h +++ b/src/helper/ipv4-static-routing-helper.h @@ -162,7 +162,6 @@ private: * assignment and prevent the compiler from happily inserting its own. */ Ipv4StaticRoutingHelper &operator = (const Ipv4StaticRoutingHelper &o); - }; } // namespace ns3 diff --git a/src/helper/ipv6-list-routing-helper.h b/src/helper/ipv6-list-routing-helper.h index 945f78e11..7bc181b6d 100644 --- a/src/helper/ipv6-list-routing-helper.h +++ b/src/helper/ipv6-list-routing-helper.h @@ -37,9 +37,24 @@ namespace ns3 { class Ipv6ListRoutingHelper : public Ipv6RoutingHelper { public: + /** + * Construct an Ipv6 Ipv6ListRoutingHelper which is used to make life easier + * for people wanting to configure routing using Ipv6. + */ Ipv6ListRoutingHelper (); + + /** + * \internal + * Destroy an Ipv6 Ipv6ListRoutingHelper. + */ virtual ~Ipv6ListRoutingHelper (); + + /** + * \brief Construct an Ipv6ListRoutingHelper from another previously + * initialized instance (Copy Constructor). + */ Ipv6ListRoutingHelper (const Ipv6ListRoutingHelper &); + /** * \returns pointer to clone of this Ipv6ListRoutingHelper * @@ -67,6 +82,11 @@ public: */ virtual Ptr Create (Ptr node) const; private: + /** + * \internal + * \brief Assignment operator declared private and not implemented to disallow + * assignment and prevent the compiler from happily inserting its own. + */ Ipv6ListRoutingHelper &operator = (const Ipv6ListRoutingHelper &o); std::list > m_list; diff --git a/src/helper/ipv6-routing-helper.h b/src/helper/ipv6-routing-helper.h index ac3536871..be6b1700b 100644 --- a/src/helper/ipv6-routing-helper.h +++ b/src/helper/ipv6-routing-helper.h @@ -40,6 +40,11 @@ class Node; class Ipv6RoutingHelper { public: + + /** + * \internal + * Destroy an Ipv6 Ipv6RoutingHelper. + */ virtual ~Ipv6RoutingHelper (); /** diff --git a/src/helper/ipv6-static-routing-helper.h b/src/helper/ipv6-static-routing-helper.h index 92cecde79..7b224504d 100644 --- a/src/helper/ipv6-static-routing-helper.h +++ b/src/helper/ipv6-static-routing-helper.h @@ -45,8 +45,15 @@ public: * \brief Constructor. */ Ipv6StaticRoutingHelper (); - Ipv6StaticRoutingHelper (const Ipv6StaticRoutingHelper &); + /** + * \brief Construct an Ipv6ListRoutingHelper from another previously + * initialized instance (Copy Constructor). + */ + Ipv6StaticRoutingHelper (const Ipv6StaticRoutingHelper &); + + /** + * \internal * \returns pointer to clone of this Ipv6StaticRoutingHelper * * This method is mainly for internal use by the other helpers; @@ -69,12 +76,33 @@ public: */ Ptr GetStaticRouting (Ptr ipv6) const; + /** + * \brief Add a multicast route to a node and net device using explicit + * Ptr and Ptr + */ void AddMulticastRoute (Ptr n, Ipv6Address source, Ipv6Address group, Ptr input, NetDeviceContainer output); + + /** + * \brief Add a multicast route to a node and device using a name string + * previously associated to the node using the Object Name Service and a + * Ptr + */ void AddMulticastRoute (std::string n, Ipv6Address source, Ipv6Address group, Ptr input, NetDeviceContainer output); + + /** + * \brief Add a multicast route to a node and device using a Ptr and a + * name string previously associated to the device using the Object Name Service. + */ void AddMulticastRoute (Ptr n, Ipv6Address source, Ipv6Address group, std::string inputName, NetDeviceContainer output); + + /** + * \brief Add a multicast route to a node and device using name strings + * previously associated to both the node and device using the Object Name + * Service. + */ void AddMulticastRoute (std::string nName, Ipv6Address source, Ipv6Address group, std::string inputName, NetDeviceContainer output); @@ -89,6 +117,11 @@ public: void SetDefaultMulticastRoute (std::string nName, std::string ndName); #endif private: + /** + * \internal + * \brief Assignment operator declared private and not implemented to disallow + * assignment and prevent the compiler from happily inserting its own. + */ Ipv6StaticRoutingHelper &operator = (const Ipv6StaticRoutingHelper &o); }; diff --git a/src/helper/mesh-helper.h b/src/helper/mesh-helper.h index c148632e5..1a343988b 100644 --- a/src/helper/mesh-helper.h +++ b/src/helper/mesh-helper.h @@ -38,9 +38,17 @@ class WifiChannel; class MeshHelper { public: + /** + * Construct a MeshHelper used to make life easier when creating 802.11s networks. + */ MeshHelper (); - static MeshHelper - Default (); + + /** + * \brief Set the helper to the default values for the MAC type, remote + * station manager and channel policy. + */ + static MeshHelper Default (); + /** * \param n0 the name of the attribute to set * \param v0 the value of the attribute to set @@ -118,6 +126,10 @@ public: SPREAD_CHANNELS, ZERO_CHANNEL }; + + /** + * \brief set the channel policy + */ void SetSpreadInterfaceChannels (ChannelPolicy); /** * \brief Set a number of interfaces in a mesh network @@ -163,10 +175,19 @@ public: std::string n5 = "", const AttributeValue &v5 = EmptyAttributeValue (), std::string n6 = "", const AttributeValue &v6 = EmptyAttributeValue (), std::string n7 = "", const AttributeValue &v7 = EmptyAttributeValue ()); + + /** + * \brief Print statistics. + */ void Report (const ns3::Ptr&, std::ostream&); + + /** + * \brief Reset statistics. + */ void ResetStats (const ns3::Ptr&); private: /** + * \internal * \returns a WifiNetDevice with ready-to-use interface */ Ptr CreateInterface (const WifiPhyHelper &phyHelper, Ptr node, uint16_t channelId) const; diff --git a/src/helper/mobility-helper.h b/src/helper/mobility-helper.h index cbce7d8fa..4a7eb4062 100644 --- a/src/helper/mobility-helper.h +++ b/src/helper/mobility-helper.h @@ -40,7 +40,16 @@ class MobilityModel; class MobilityHelper { public: + /** + * Construct a Mobility Helper which is used to make life easier when working + * with mobility models. + */ MobilityHelper (); + + /** + * \internal + * Destroy a Mobility Helper + */ ~MobilityHelper (); /** @@ -241,6 +250,9 @@ public: static void EnableAsciiAll (std::ostream &os); private: + /** + * \internal + */ static void CourseChanged (std::ostream *os, Ptr mobility); std::vector > m_mobilityStack; ObjectFactory m_mobility; diff --git a/src/helper/net-device-container.h b/src/helper/net-device-container.h index d5f9313fc..79db52daf 100644 --- a/src/helper/net-device-container.h +++ b/src/helper/net-device-container.h @@ -29,6 +29,14 @@ namespace ns3 { /** * \brief holds a vector of ns3::NetDevice pointers * + * Typically ns-3 NetDevices are installed on nodes using a net device + * helper. The helper Install method takes a NodeContainer which holds + * some number of Ptr. For each of the Nodes in the NodeContainer + * the helper will instantiate a net device, add a MAC address and a queue + * to the device and install it to the node. For each of the devices, the + * helper also adds the device into a Container for later use by the caller. + * This is that container used to hold the Ptr which are + * instantiated by the device helper. */ class NetDeviceContainer { @@ -39,18 +47,26 @@ public: * Create an empty NetDeviceContainer. */ NetDeviceContainer (); + /** * \param dev a device to add to the container * - * Create a NetDeviceContainer with exactly one device + * Create a NetDeviceContainer with exactly one net device that has previously + * been instantiated */ NetDeviceContainer (Ptr dev); + /** - * \param devName The name of a device to add to the container + * Create a NetDeviceContainer with exactly one device which has been + * previously instantiated and assigned a name using the Object name + * service. This NetDevice is specified by its assigned name. + * + * \param devName The name of the device to add to the container * * Create a NetDeviceContainer with exactly one device */ NetDeviceContainer (std::string devName); + /** * \param a a device container * \param b another device container @@ -69,40 +85,112 @@ public: NetDeviceContainer (const NetDeviceContainer &a, const NetDeviceContainer &b); /** - * \returns an iterator which points to the start of the array of pointers. + * \brief Get an iterator which refers to the first NetDevice in the + * container. + * + * NetDevices can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the iterator method and is typically used in a + * for-loop to run through the NetDevices + * + * \code + * NetDeviceContainer::Iterator i; + * for (i = container.Begin (); i != container.End (); ++i) + * { + * (*i)->method (); // some NetDevice method + * } + * \endcode + * + * \returns an iterator which refers to the first NetDevice in the container. */ Iterator Begin (void) const; + /** - * \returns an iterator which points to the end of the array of pointers. + * \brief Get an iterator which indicates past-the-last NetDevice in the + * container. + * + * NetDevices can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the iterator method and is typically used in a + * for-loop to run through the NetDevices + * + * \code + * NetDeviceContainer::Iterator i; + * for (i = container.Begin (); i != container.End (); ++i) + * { + * (*i)->method (); // some NetDevice method + * } + * \endcode + * + * \returns an iterator which indicates an ending condition for a loop. */ Iterator End (void) const; /** - * \returns the number of netdevice pointers stored in this container. + * \brief Get the number of Ptr stored in this container. + * + * NetDevices can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the direct method and is typically used to + * define an ending condition in a for-loop that runs through the stored + * NetDevices + * + * \code + * uint32_t nDevices = container.GetN (); + * for (uint32_t i = 0 i < nDevices; ++i) + * { + * Ptr p = container.Get (i) + * i->method (); // some NetDevice method + * } + * \endcode + * + * \returns the number of Ptr stored in this container. */ uint32_t GetN (void) const; + /** - * \param i the index of the requested netdevice pointer. - * \returns the requested netdevice pointer. + * \brief Get the Ptr stored in this container at a given + * index. + * + * NetDevices can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the direct method and is used to retrieve the + * indexed Ptr. + * + * \code + * uint32_t nDevices = container.GetN (); + * for (uint32_t i = 0 i < nDevices; ++i) + * { + * Ptr p = container.Get (i) + * i->method (); // some NetDevice method + * } + * \endcode + * + * \param i the index of the requested device pointer. + * \returns the requested device pointer. */ Ptr Get (uint32_t i) const; /** - * \param other another netdevice container + * \brief Append the contents of another NetDeviceContainer to the end of + * this container. * - * Append to the end of this container the other input container. + * \param The NetDeviceContainer to append. */ void Add (NetDeviceContainer other); + /** - * \param device another netdevice pointer. + * \brief Append a single Ptr to this container. * - * Append to the end of this container the input netdevice pointer. + * \param application The Ptr to append. */ void Add (Ptr device); + /** - * \param deviceName The name of another netdevice to add. + * \brief Append to this container the single Ptr referred to + * via its object name service registered name. * - * Append to the end of this container the input netdevice pointer. + * \param name The name of the NetDevice Object to add to the container. */ void Add (std::string deviceName); diff --git a/src/helper/node-container.h b/src/helper/node-container.h index e4def7b63..0e2634be5 100644 --- a/src/helper/node-container.h +++ b/src/helper/node-container.h @@ -29,6 +29,11 @@ namespace ns3 { /** * \brief keep track of a set of node pointers. * + * Typically ns-3 helpers operate on more than one node at a time. For example + * a device helper may want to install devices on a large number of similar + * nodes. The helper Install methods usually take a NodeContainer as a + * parameter. NodeContainers hold the multiple Ptr which are used + * to refer to the nodes. */ class NodeContainer { @@ -39,25 +44,31 @@ public: * Create an empty NodeContainer. */ NodeContainer (); + /** - * \param node a node to add to the container + * Create a NodeContainer with exactly one node which has been previously + * instantiated. The single Node is specified by a smart pointer. * - * Create a NodeContainer with exactly one node. + * \param node The Ptr to add to the container. */ NodeContainer (Ptr node); + /** - * \param nodeName The name of a node to add to the container + * Create a NodeContainer with exactly one node which has been previously + * instantiated and assigned a name using the Object Name Service. This + * Node is then specified by its assigned name. * - * Create a NodeContainer with exactly one node. + * \param name The name of the Node Object to add to the container. */ NodeContainer (std::string nodeName); + /** - * \param a a node container - * \param b another node container - * - * Create a node container which is a concatenation of the two input + * Create a node container which is a concatenation of two input * NodeContainers. * + * \param a The first NodeContainer + * \param b The second NodeContainer + * * \note A frequently seen idiom that uses these constructors involves the * implicit conversion by constructor of Ptr. When used, two * Ptr will be passed to this constructor instead of NodeContainer&. @@ -68,60 +79,197 @@ public: */ NodeContainer (const NodeContainer &a, const NodeContainer &b); + /** + * Create a node container which is a concatenation of three input + * NodeContainers. + * + * \param a The first NodeContainer + * \param b The second NodeContainer + * \param c The third NodeContainer + * + * \note A frequently seen idiom that uses these constructors involves the + * implicit conversion by constructor of Ptr. When used, two + * Ptr will be passed to this constructor instead of NodeContainer&. + * C++ will notice the implicit conversion path that goes through the + * NodeContainer (Ptr node) constructor above. Using this conversion + * one may provide optionally provide arguments of Ptr to these + * constructors. + */ NodeContainer (const NodeContainer &a, const NodeContainer &b, const NodeContainer &c); + + /** + * Create a node container which is a concatenation of four input + * NodeContainers. + * + * \param a The first NodeContainer + * \param b The second NodeContainer + * \param c The third NodeContainer + * \param d The fourth NodeContainer + * + * \note A frequently seen idiom that uses these constructors involves the + * implicit conversion by constructor of Ptr. When used, two + * Ptr will be passed to this constructor instead of NodeContainer&. + * C++ will notice the implicit conversion path that goes through the + * NodeContainer (Ptr node) constructor above. Using this conversion + * one may provide optionally provide arguments of Ptr to these + * constructors. + */ NodeContainer (const NodeContainer &a, const NodeContainer &b, const NodeContainer &c, const NodeContainer &d); + + /** + * Create a node container which is a concatenation of five input + * NodeContainers. + * + * \param a The first NodeContainer + * \param b The second NodeContainer + * \param c The third NodeContainer + * \param d The fourth NodeContainer + * \param e The fifth NodeContainer + * + * \note A frequently seen idiom that uses these constructors involves the + * implicit conversion by constructor of Ptr. When used, two + * Ptr will be passed to this constructor instead of NodeContainer&. + * C++ will notice the implicit conversion path that goes through the + * NodeContainer (Ptr node) constructor above. Using this conversion + * one may provide optionally provide arguments of Ptr to these + * constructors. + */ NodeContainer (const NodeContainer &a, const NodeContainer &b, const NodeContainer &c, const NodeContainer &d, const NodeContainer &e); /** - * \returns an iterator to the start of the vector of node pointers. + * \brief Get an iterator which refers to the first Node in the + * container. + * + * Nodes can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the iterator method and is typically used in a + * for-loop to run through the Nodes + * + * \code + * NodeContainer::Iterator i; + * for (i = container.Begin (); i != container.End (); ++i) + * { + * (*i)->method (); // some Node method + * } + * \endcode + * + * \returns an iterator which refers to the first Node in the container. */ Iterator Begin (void) const; + /** - * \returns an iterator to the end of the vector of node pointers. + * \brief Get an iterator which indicates past-the-last Node in the + * container. + * + * Nodes can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the iterator method and is typically used in a + * for-loop to run through the Nodes + * + * \code + * NodeContainer::Iterator i; + * for (i = container.Begin (); i != container.End (); ++i) + * { + * (*i)->method (); // some Node method + * } + * \endcode + * + * \returns an iterator which indicates an ending condition for a loop. */ Iterator End (void) const; /** - * \returns the number of node pointers stored in this NodeContainer. + * \brief Get the number of Ptr stored in this container. + * + * Nodes can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the direct method and is typically used to + * define an ending condition in a for-loop that runs through the stored + * Nodes + * + * \code + * uint32_t nNodes = continer.GetN (); + * for (uint32_t i = 0 i < nNodes; ++i) + * { + * Ptr p = continer.Get (i) + * i->method (); // some Node method + * } + * \endcode + * + * \returns the number of Ptr stored in this container. */ uint32_t GetN (void) const; + /** + * \brief Get the Ptr stored in this container at a given + * index. + * + * Nodes can be retrieved from the container in two ways. First, + * directly by an index into the container, and second, using an iterator. + * This method is used in the direct method and is used to retrieve the + * indexed Ptr. + * + * \code + * uint32_t nNodes = container.GetN (); + * for (uint32_t i = 0 i < nNodes; ++i) + * { + * Ptr p = container.Get (i) + * i->method (); // some Node method + * } + * \endcode + * * \param i the index of the requested node pointer. * \returns the requested node pointer. */ Ptr Get (uint32_t i) const; /** - * \param n the number of nodes to create + * \brief Create n nodes and append pointers to them to the end of this + * NodeContainer. * - * Create n nodes and append pointers to them to the end of this NodeContainer. + * Nodes are at the heart of any ns-3 simulation. One of the first tasks that + * any simulation needs to do is to create a number of nodes. This method + * automates that task. + * + * \param n The number of Nodes to create */ void Create (uint32_t n); + /** - * \param other another NodeContainer + * \brief Append the contents of another NodeContainer to the end of + * this container. * - * Append the node pointers from the input NodeContainer at the end - * of this NodeContainer. + * \param The NodeContainer to append. */ void Add (NodeContainer other); + /** - * \param node a node pointer + * \brief Append a single Ptr to this container. * - * Append the input node pointer at the end of this NodeContainer. + * \param node The Ptr to append. */ void Add (Ptr node); + /** - * \param nodeName The name of a node + * \brief Append to this container the single Ptr referred to + * via its object name service registered name. * - * Append the input node pointer at the end of this NodeContainer. + * \param nodeName The name of the Node Object to add to the container. */ void Add (std::string nodeName); /** - * \returns a container which contains a list of _all_ nodes - * created through NodeContainer::Create and stored - * in ns3::NodeList. + * \brief Create a NodeContainer that contains a list of _all_ nodes + * created through NodeContainer::Create() and stored in the + * ns3::NodeList. + * + * Whenever a Node is created, a Ptr is added to a global list of all + * nodes in the system. It is sometimes useful to be able to get to all + * nodes in one place. This method creates a NodeContainer that is + * initialized to contain all of the simulation nodes, + * + * \returns a NoceContainer which contains a list of all Nodes. */ static NodeContainer GetGlobal (void);