From 5fcca3808fe8136c68db11dcf52e6920aea90f55 Mon Sep 17 00:00:00 2001 From: Robert Ammon Date: Wed, 30 Aug 2017 08:38:06 -0700 Subject: [PATCH] aodv: Fix doxygen warnings --- src/aodv/examples/aodv.cc | 5 +- src/aodv/model/aodv-dpd.h | 26 +++++++-- src/aodv/model/aodv-id-cache.h | 26 +++++++-- src/aodv/model/aodv-neighbor.h | 61 ++++++++++++++----- src/aodv/model/aodv-packet.h | 56 ++++++++++++++---- src/aodv/model/aodv-routing-protocol.h | 71 ++++++++++++++++++---- src/aodv/model/aodv-rqueue.h | 53 ++++++++++++++--- src/aodv/model/aodv-rtable.h | 81 ++++++++++++++++++++------ src/aodv/test/bug-772.h | 5 +- 9 files changed, 311 insertions(+), 73 deletions(-) diff --git a/src/aodv/examples/aodv.cc b/src/aodv/examples/aodv.cc index b73b5204d..f8daca458 100644 --- a/src/aodv/examples/aodv.cc +++ b/src/aodv/examples/aodv.cc @@ -57,7 +57,10 @@ public: bool Configure (int argc, char **argv); /// Run simulation void Run (); - /// Report results + /** + * Report results + * \param os the output stream + */ void Report (std::ostream & os); private: diff --git a/src/aodv/model/aodv-dpd.h b/src/aodv/model/aodv-dpd.h index d91a18a46..6a5d8a62e 100644 --- a/src/aodv/model/aodv-dpd.h +++ b/src/aodv/model/aodv-dpd.h @@ -35,21 +35,35 @@ namespace aodv { * * \brief Helper class used to remember already seen packets and detect duplicates. * - * Currently duplicate detection is based on uinique packet ID given by Packet::GetUid () - * This approach is known to be weak and should be changed. + * Currently duplicate detection is based on unique packet ID given by Packet::GetUid () + * This approach is known to be weak (ns3::Packet UID is an internal identifier and not intended for logical uniqueness in models) and should be changed. */ class DuplicatePacketDetection { public: - /// C-tor + /** + * Constructor + * \param lifetime the lifetime for added entries + */ DuplicatePacketDetection (Time lifetime) : m_idCache (lifetime) { } - /// Check that the packet is duplicated. If not, save information about this packet. + /** + * Check if the packet is a duplicate. If not, save information about this packet. + * \param p the packet to check + * \param header the IP header to check + * \returns true if duplicate + */ bool IsDuplicate (Ptr p, const Ipv4Header & header); - /// Set duplicate records lifetimes + /** + * Set duplicate record lifetime + * \param lifetime the lifetime for duplicate records + */ void SetLifetime (Time lifetime); - /// Get duplicate records lifetimes + /** + * Get duplicate record lifetime + * \returns the duplicate record lifetime + */ Time GetLifetime () const; private: /// Impl diff --git a/src/aodv/model/aodv-id-cache.h b/src/aodv/model/aodv-id-cache.h index 863b23bac..4f659222b 100644 --- a/src/aodv/model/aodv-id-cache.h +++ b/src/aodv/model/aodv-id-cache.h @@ -43,22 +43,38 @@ namespace aodv { class IdCache { public: - /// c-tor + /** + * constructor + * \param lifetime the lifetime for added entries + */ IdCache (Time lifetime) : m_lifetime (lifetime) { } - /// Check that entry (addr, id) exists in cache. Add entry, if it doesn't exist. + /** + * Check that entry (addr, id) exists in cache. Add entry, if it doesn't exist. + * \param addr the IP address + * \param id the cache entry ID + * \returns true if the pair exists + */ bool IsDuplicate (Ipv4Address addr, uint32_t id); /// Remove all expired entries void Purge (); - /// Return number of entries in cache + /** + * \returns number of entries in cache + */ uint32_t GetSize (); - /// Set lifetime for future added entries. + /** + * Set lifetime for future added entries. + * \param lifetime the lifetime for entries + */ void SetLifetime (Time lifetime) { m_lifetime = lifetime; } - /// Return lifetime for existing entries in cache + /** + * Return lifetime for existing entries in cache + * \returns thhe lifetime + */ Time GetLifeTime () const { return m_lifetime; diff --git a/src/aodv/model/aodv-neighbor.h b/src/aodv/model/aodv-neighbor.h index d1bb4597a..8e3fd1193 100644 --- a/src/aodv/model/aodv-neighbor.h +++ b/src/aodv/model/aodv-neighbor.h @@ -47,7 +47,10 @@ class RoutingProtocol; class Neighbors { public: - /// c-tor + /** + * constructor + * \param delay the delay time for purging the list of neighbors + */ Neighbors (Time delay); /// Neighbor description struct Neighbor @@ -76,11 +79,23 @@ public: { } }; - /// Return expire time for neighbor node with address addr, if exists, else return 0. + /** + * Return expire time for neighbor node with address addr, if exists, else return 0. + * \param addr the IP address of the neighbor node + * \returns the expire time for the neighbor node + */ Time GetExpireTime (Ipv4Address addr); - /// Check that node with address addr is neighbor + /** + * Check that node with address addr is neighbor + * \param addr the IP address to check + * \returns true if the node with IP address is a neighbor + */ bool IsNeighbor (Ipv4Address addr); - /// Update expire time for entry with address addr, if it exists, else add new entry + /** + * Update expire time for entry with address addr, if it exists, else add new entry + * \param addr the IP address to check + * \param expire the expire time for the address + */ void Update (Ipv4Address addr, Time expire); /// Remove all expired entries void Purge (); @@ -92,22 +107,37 @@ public: m_nb.clear (); } - /// Add ARP cache to be used to allow layer 2 notifications processing - void AddArpCache (Ptr); - /// Don't use given ARP cache any more (interface is down) - void DelArpCache (Ptr); - /// Get callback to ProcessTxError + /** + * Add ARP cache to be used to allow layer 2 notifications processing + * \param a pointer to the ARP cache to add + */ + void AddArpCache (Ptr a); + /** + * Don't use given ARP cache any more (interface is down) + * \param a pointer to the ARP cache to delete + */ + void DelArpCache (Ptr a); + /** + * Get callback to ProcessTxError + * \returns the callback function + */ Callback GetTxErrorCallback () const { return m_txErrorCallback; } - /// Handle link failure callback + /** + * Set link failure callback + * \param cb the callback function + */ void SetCallback (Callback cb) { m_handleLinkFailure = cb; } - /// Handle link failure callback + /** + * Get link failure callback + * \returns the link failure callback + */ Callback GetCallback () const { return m_handleLinkFailure; @@ -125,8 +155,13 @@ private: /// list of ARP cached to be used for layer 2 notifications processing std::vector > m_arp; - /// Find MAC address by IP using list of ARP caches - Mac48Address LookupMacAddress (Ipv4Address); + /** + * Find MAC address by IP using list of ARP caches + * + * \param addr the IP address to lookup + * \returns the MAC address for the IP address + */ + Mac48Address LookupMacAddress (Ipv4Address addr); /// Process layer 2 TX error notification void ProcessTxError (WifiMacHeader const &); }; diff --git a/src/aodv/model/aodv-packet.h b/src/aodv/model/aodv-packet.h index ad0a191d3..7ede84465 100644 --- a/src/aodv/model/aodv-packet.h +++ b/src/aodv/model/aodv-packet.h @@ -57,7 +57,10 @@ enum MessageType class TypeHeader : public Header { public: - /// c-tor + /** + * constructor + * \param t the AODV RREQ type + */ TypeHeader (MessageType t = AODVTYPE_RREQ); /** @@ -71,12 +74,17 @@ public: uint32_t Deserialize (Buffer::Iterator start); void Print (std::ostream &os) const; - /// Return type + /** + * \returns the type + */ MessageType Get () const { return m_type; } - /// Check that type if valid + /** + * Check that type if valid + * \returns true if the type is valid + */ bool IsValid () const { return m_valid; @@ -123,8 +131,19 @@ std::ostream & operator<< (std::ostream & os, TypeHeader const & h); class RreqHeader : public Header { public: - /// c-tor - RreqHeader (uint8_t flags = 0, uint8_t reserved = 0, uint8_t hopCount = 0, + /** + * constructor + * + * \param flags the message flags (0) + * \param reserved the reserved bits (0) + * \param hopCount the hop count + * \param requestID the request ID + * \param dst the destination IP address + * \param dstSeqNo the destination sequence number + * \param origin the origin IP address + * \param originSeqNo the origin sequence number + */ + RreqHeader (uint8_t flags = 0, uint8_t reserved = 0, uint8_t hopCount = 0, uint32_t requestID = 0, Ipv4Address dst = Ipv4Address (), uint32_t dstSeqNo = 0, Ipv4Address origin = Ipv4Address (), uint32_t originSeqNo = 0); @@ -316,7 +335,16 @@ std::ostream & operator<< (std::ostream & os, RreqHeader const &); class RrepHeader : public Header { public: - /// c-tor + /** + * constructor + * + * \param prefixSize the prefix size (0) + * \param hopCount the hop count (0) + * \param dst the destination IP address + * \param dstSeqNo the destination sequence number + * \param origin the origin IP address + * \param lifetime the lifetime + */ RrepHeader (uint8_t prefixSize = 0, uint8_t hopCount = 0, Ipv4Address dst = Ipv4Address (), uint32_t dstSeqNo = 0, Ipv4Address origin = Ipv4Address (), Time lifetime = MilliSeconds (0)); @@ -429,7 +457,13 @@ public: */ uint8_t GetPrefixSize () const; - /// Configure RREP to be a Hello message + /** + * Configure RREP to be a Hello message + * + * \param src the source IP address + * \param srcSeqNo the source sequence number + * \param lifetime the lifetime of the message + */ void SetHello (Ipv4Address src, uint32_t srcSeqNo, Time lifetime); /** @@ -469,7 +503,7 @@ std::ostream & operator<< (std::ostream & os, RrepHeader const &); class RrepAckHeader : public Header { public: - /// c-tor + /// constructor RrepAckHeader (); /** @@ -523,7 +557,7 @@ std::ostream & operator<< (std::ostream & os, RrepAckHeader const &); class RerrHeader : public Header { public: - /// c-tor + /// constructor RerrHeader (); /** @@ -564,7 +598,9 @@ public: bool RemoveUnDestination (std::pair & un); /// Clear header void Clear (); - /// Return number of unreachable destinations in RERR message + /** + * \returns number of unreachable destinations in RERR message + */ uint8_t GetDestCount () const { return (uint8_t)m_unreachableDstSeqNo.size (); diff --git a/src/aodv/model/aodv-routing-protocol.h b/src/aodv/model/aodv-routing-protocol.h index 86422b127..4123c61bd 100644 --- a/src/aodv/model/aodv-routing-protocol.h +++ b/src/aodv/model/aodv-routing-protocol.h @@ -58,7 +58,7 @@ public: static TypeId GetTypeId (void); static const uint32_t AODV_PORT; - /// c-tor + /// constructor RoutingProtocol (); virtual ~RoutingProtocol (); virtual void DoDispose (); @@ -250,13 +250,29 @@ private: private: /// Start protocol operation void Start (); - /// Queue packet and send route request + /** + * Queue packet and send route request + * + * \param p the packet to route + * \param header the IP header + * \param ucb the UnicastForwardCallback function + * \param ecb the ErrorCallback function + */ void DeferredRouteOutput (Ptr p, const Ipv4Header & header, UnicastForwardCallback ucb, ErrorCallback ecb); - /// If route exists and valid, forward packet. + /** + * If route exists and is valid, forward packet. + * + * \param p the packet to route + * \param header the IP header + * \param ucb the UnicastForwardCallback function + * \param ecb the ErrorCallback function + * \returns true if forwarded + */ bool Forwarding (Ptr p, const Ipv4Header & header, UnicastForwardCallback ucb, ErrorCallback ecb); /** * Repeated attempts by a source node at route discovery for a single destination * use the expanding ring search technique. + * \param dst the destination IP address */ void ScheduleRreqRetry (Ipv4Address dst); /** @@ -272,15 +288,40 @@ private: * \param sender is supposed to be IP address of my neighbor. */ void UpdateRouteToNeighbor (Ipv4Address sender, Ipv4Address receiver); - /// Check that packet is send from own interface + /** + * Test whether the provided address is assigned to an interface on this node + * \param src the source IP address + * \returns true if the IP address is the node's IP address + */ bool IsMyOwnAddress (Ipv4Address src); - /// Find unicast socket with local interface address iface + /** + * Find unicast socket with local interface address iface + * + * \param iface the interface + * \returns the socket associated with the interface + */ Ptr FindSocketWithInterfaceAddress (Ipv4InterfaceAddress iface) const; - /// Find subnet directed broadcast socket with local interface address iface + /** + * Find subnet directed broadcast socket with local interface address iface + * + * \param iface the interface + * \returns the socket associated with the interface + */ Ptr FindSubnetBroadcastSocketWithInterfaceAddress (Ipv4InterfaceAddress iface) const; - /// Process hello message + /** + * Process hello message + * + * \param rrepHeader RREP message header + * \param receiverIfaceAddr receiver interface IP address + */ void ProcessHello (RrepHeader const & rrepHeader, Ipv4Address receiverIfaceAddr); - /// Create loopback route for given header + /** + * Create loopback route for given header + * + * \param header the IP header + * \param oif the output interface net device + * \returns the route + */ Ptr LoopbackRoute (const Ipv4Header & header, Ptr oif) const; ///\name Receive control packets @@ -350,10 +391,18 @@ private: void RerrRateLimitTimerExpire (); /// Map IP address + RREQ timer. std::map m_addressReqTimer; - /// Handle route discovery process + /** + * Handle route discovery process + * \param dst the destination IP address + */ void RouteRequestTimerExpire (Ipv4Address dst); - /// Mark link to neighbor node as unidirectional for blacklistTimeout - void AckTimerExpire (Ipv4Address neighbor, Time blacklistTimeout); + /** + * Mark link to neighbor node as unidirectional for blacklistTimeout + * + * \param neighbor the IP address of the neightbor node + * \param blacklistTimeout the black list timeout time + */ + void AckTimerExpire (Ipv4Address neighbor, Time blacklistTimeout); /// Provides uniform random variables. Ptr m_uniformRandomVariable; diff --git a/src/aodv/model/aodv-rqueue.h b/src/aodv/model/aodv-rqueue.h index 581624e01..7f8ac704a 100644 --- a/src/aodv/model/aodv-rqueue.h +++ b/src/aodv/model/aodv-rqueue.h @@ -47,7 +47,15 @@ public: typedef Ipv4RoutingProtocol::UnicastForwardCallback UnicastForwardCallback; /// IPv4 routing error callback typedef typedef Ipv4RoutingProtocol::ErrorCallback ErrorCallback; - /// c-tor + /** + * constructor + * + * \param pa the packet to add to the queue + * \param h the Ipv4Header + * \param ucb the UnicastForwardCallback function + * \param ecb the ErrorCallback function + * \param exp the expiration time + */ QueueEntry (Ptr pa = 0, Ipv4Header const & h = Ipv4Header (), UnicastForwardCallback ucb = UnicastForwardCallback (), ErrorCallback ecb = ErrorCallback (), Time exp = Simulator::Now ()) @@ -172,21 +180,46 @@ private: class RequestQueue { public: - /// Default c-tor + /** + * constructor + * + * \param maxLen the maximum length + * \param routeToQueueTimeout the route to queue timeout + */ RequestQueue (uint32_t maxLen, Time routeToQueueTimeout) : m_maxLen (maxLen), m_queueTimeout (routeToQueueTimeout) { } - /// Push entry in queue, if there is no entry with the same packet and destination address in queue. + /** + * Push entry in queue, if there is no entry with the same packet and destination address in queue. + * \param entry the queue entry + * \returns true if the entry is queued + */ bool Enqueue (QueueEntry & entry); - /// Return first found (the earliest) entry for given destination + /** + * Return first found (the earliest) entry for given destination + * + * \param dst the destination IP address + * \param entry the queue entry + * \returns true if the entry is dequeued + */ bool Dequeue (Ipv4Address dst, QueueEntry & entry); - /// Remove all packets with destination IP address dst + /** + * Remove all packets with destination IP address dst + * \param dst the destination IP address + */ void DropPacketWithDst (Ipv4Address dst); - /// Finds whether a packet with destination dst exists in the queue + /** + * Finds whether a packet with destination dst exists in the queue + * + * \param dst the destination IP address + * \returns true if an entry with the IP address is found + */ bool Find (Ipv4Address dst); - /// Number of entries + /** + * \returns the number of entries + */ uint32_t GetSize (); // Fields @@ -228,7 +261,11 @@ private: std::vector m_queue; /// Remove all expired entries void Purge (); - /// Notify that packet is dropped from queue by timeout + /** + * Notify that packet is dropped from queue by timeout + * \param en the queue entry to drop + * \param reason the reason to drop the entry + */ void Drop (QueueEntry en, std::string reason); /// The maximum number of packets that we allow a routing protocol to buffer. uint32_t m_maxLen; diff --git a/src/aodv/model/aodv-rtable.h b/src/aodv/model/aodv-rtable.h index 592180059..b70e30e8a 100644 --- a/src/aodv/model/aodv-rtable.h +++ b/src/aodv/model/aodv-rtable.h @@ -59,8 +59,19 @@ enum RouteFlags class RoutingTableEntry { public: - /// c-to - RoutingTableEntry (Ptr dev = 0,Ipv4Address dst = Ipv4Address (), bool vSeqNo = false, uint32_t m_seqNo = 0, + /** + * constructor + * + * \param dev the device + * \param dst the destination IP address + * \param vSeqNo verify sequence number flag + * \param seqNo the sequence number + * \param iface the interface + * \param hops the number of hops + * \param nextHop the IP address of the next hop + * \param lifetime the lifetime of the entry + */ + RoutingTableEntry (Ptr dev = 0,Ipv4Address dst = Ipv4Address (), bool vSeqNo = false, uint32_t seqNo = 0, Ipv4InterfaceAddress iface = Ipv4InterfaceAddress (), uint16_t hops = 0, Ipv4Address nextHop = Ipv4Address (), Time lifetime = Simulator::Now ()); @@ -100,13 +111,16 @@ public: void GetPrecursors (std::vector & prec) const; //\} - /// Mark entry as "down" (i.e. disable it) + /** + * Mark entry as "down" (i.e. disable it) + * \param badLinkLifetime duration to keep entry marked as invalid + */ void Invalidate (Time badLinkLifetime); // Fields /** * Get destination address function - * \returns the IPv4 destiantion address + * \returns the IPv4 destination address */ Ipv4Address GetDestination () const { @@ -344,11 +358,11 @@ private: */ Time m_lifeTime; /** Ip route, include - * - destination address - * - source address - * - next hop address (gateway) - * - output device - */ + * - destination address + * - source address + * - next hop address (gateway) + * - output device + */ Ptr m_ipv4Route; /// Output interface address Ipv4InterfaceAddress m_iface; @@ -374,9 +388,12 @@ private: class RoutingTable { public: - /// c-tor + /** + * constructor + * \param t the routing table entry lifetime + */ RoutingTable (Time t); - ///\name Handle life time of invalid route + ///\name Handle lifetime of invalid route //\{ Time GetBadLinkLifetime () const { @@ -406,13 +423,32 @@ public: * \return true on success */ bool LookupRoute (Ipv4Address dst, RoutingTableEntry & rt); - /// Lookup route in VALID state + /** + * Lookup route in VALID state + * \param dst destination address + * \param rt entry with destination address dst, if exists + * \return true on success + */ bool LookupValidRoute (Ipv4Address dst, RoutingTableEntry & rt); - /// Update routing table + /** + * Update routing table + * \param rt entry with destination address dst, if exists + * \return true on success + */ bool Update (RoutingTableEntry & rt); - /// Set routing table entry flags + /** + * Set routing table entry flags + * \param dst destination address + * \param state the routing flags + * \return true on success + */ bool SetEntryState (Ipv4Address dst, RouteFlags state); - /// Lookup routing entries with next hop Address dst and not empty list of precursors. + /** + * Lookup routing entries with next hop Address dst and not empty list of precursors. + * + * \param nextHop the next hop IP address + * \param unreachable + */ void GetListOfDestinationWithNextHop (Ipv4Address nextHop, std::map & unreachable); /** * Update routing entries with this destination as follows: @@ -423,7 +459,10 @@ public: * \param unreachable routes to invalidate */ void InvalidateRoutesWithDst (std::map const & unreachable); - /// Delete all route from interface with address iface + /** + * Delete all route from interface with address iface + * \param iface the interface IP address + */ void DeleteAllRoutesFromInterface (Ipv4InterfaceAddress iface); /// Delete all entries from routing table void Clear () @@ -438,7 +477,10 @@ public: * \return true on success */ bool MarkLinkAsUnidirectional (Ipv4Address neighbor, Time blacklistTimeout); - /// Print routing table + /** + * Print routing table + * \param stream the output stream + */ void Print (Ptr stream) const; private: @@ -446,7 +488,10 @@ private: std::map m_ipv4AddressEntry; /// Deletion time for invalid routes Time m_badLinkLifetime; - /// const version of Purge, for use by Print() method + /** + * const version of Purge, for use by Print() method + * \param table the routing table entry to purge + */ void Purge (std::map &table) const; }; diff --git a/src/aodv/test/bug-772.h b/src/aodv/test/bug-772.h index ec782da34..6a191bed1 100644 --- a/src/aodv/test/bug-772.h +++ b/src/aodv/test/bug-772.h @@ -76,7 +76,10 @@ private: void CheckResults (); /// Go void DoRun (); - /// receive data + /** + * Receive data function + * \param socket the socket to receive from + */ void HandleRead (Ptr socket); /// Receiving socket