From 9f44a9d6a4a76469f9bfb6cc87f3e7041f0f24cf Mon Sep 17 00:00:00 2001
From: Craig Dowell <craigdo@ee.washington.edu>
Date: Thu, 12 Jul 2007 10:47:12 -0700
Subject: [PATCH] dox for candidate queue

---
 src/routing/candidate-queue.cc |   2 -
 src/routing/candidate-queue.h  | 109 ++++++++++++++++++++++++++++++++-
 src/routing/static-router.h    |   8 +++
 3 files changed, 115 insertions(+), 4 deletions(-)

diff --git a/src/routing/candidate-queue.cc b/src/routing/candidate-queue.cc
index 7b5f9ba96..bec333936 100644
--- a/src/routing/candidate-queue.cc
+++ b/src/routing/candidate-queue.cc
@@ -45,7 +45,6 @@ CandidateQueue::Clear (void)
     }
 }
 
-
   void
 CandidateQueue::Push (SPFVertex *vNew)
 {
@@ -109,7 +108,6 @@ CandidateQueue::Size (void)
   return m_candidates.size ();
 }
 
-
   SPFVertex *
 CandidateQueue::Find (const Ipv4Address addr)
 {
diff --git a/src/routing/candidate-queue.h b/src/routing/candidate-queue.h
index 5d266e7c5..c5bfb3c39 100644
--- a/src/routing/candidate-queue.h
+++ b/src/routing/candidate-queue.h
@@ -23,19 +23,112 @@
 
 namespace ns3 {
 
+/**  
+ * \brief a Candidate Queue used in static routing.
+ *
+ * The CandidateQueue is used in the OSPF shortest path computations.  It
+ * is a priority queue used to store candidates for the shortest path to a
+ * given network.  
+ *
+ * The queue holds Shortest Path First Vertex pointers and orders them
+ * according to the lowest value of the field m_distanceFromRoot.  Remaining
+ * vertices are ordered according to increasing distance.  This implements a
+ * priority queue.
+ *
+ * Although a STL priority_queue almost does what we want, the requirement
+ * for a Find () operation, the dynamic nature of the data and the derived
+ * requirement for a Reorder () operation led us to implement this simple 
+ * enhanced priority queue.
+ */
 class CandidateQueue
 {
 public:
+  /**
+   * Create an empty SPF Candidate Queue.  
+   *
+   * @see SPFVertex
+   */
   CandidateQueue ();
+  /**
+   * Destroy an SPF Candidate Queue and release any resources held by the 
+   * contents.
+   *
+   * @see SPFVertex
+   */
   virtual ~CandidateQueue ();
-
+  /**
+   * Empty the Candidate Queue and release all of the resources associated 
+   * with the Shortest Path First Vertex pointers in the queue.
+   *
+   * @see SPFVertex
+   */
   void          Clear (void);
-  void          Push (SPFVertex *v);
+  /**
+   * Push a Shortest Path First Vertex pointer onto the queue according to the
+   * priority scheme.
+   * 
+   * On completion, the top of the queue will hold the Shortest Path First
+   * Vertex pointer that points to a vertex having lowest value of the field
+   * m_distanceFromRoot.  Remaining vertices are ordered according to 
+   * increasing distance.
+   *
+   * @see SPFVertex
+   * @param vNew The Shortest Path First Vertex to add to the queue.
+   */
+  void          Push (SPFVertex *vNew);
+  /**
+   * Pop the Shortest Path First Vertex pointer at the top of the queue and
+   * release the resources associated with the vertex.
+   *
+   * @see SPFVertex
+   * @see Top ()
+   */
   void          Pop (void);
+  /**
+   * Return the Shortest Path First Vertex pointer at the top of the queue.  
+   * This method does not pop the SPFVertex* off of the queue, it simply 
+   * returns the pointer.
+   *
+   * @see SPFVertex
+   * @see Pop ()
+   * @returns The Shortest Path First Vertex pointer at the top of the queue.
+   */
   SPFVertex*    Top (void);
+  /**
+   * Test the Candidate Queue to determine if it is empty.
+   *
+   * @returns True if the queue is empty, false otherwise.
+   */
   bool          Empty (void);
+  /**
+   * Return the number of Shortest Path First Vertex pointers presently
+   * stored in the Candidate Queue.
+   *
+   * @see SPFVertex
+   * @returns The number of SPFVertex* pointers in the Candidate Queue.
+   */
   uint32_t      Size (void);
+  /**
+   * Searches the Candidate Queue for a Shortest Path First Vertex pointer
+   * that points to a vertex having the given IP address.
+   *
+   * @see SPFVertex
+   * @param addr The IP address to search for.
+   * @returns The SPFVertex* pointer corresponding to the given IP address.
+   */
   SPFVertex*    Find (const Ipv4Address addr);
+  /**
+   * Reorders the Candidate Queue according to the priority scheme.  On 
+   * completion, the top of the queue will hold the Shortest Path First
+   * Vertex pointer that points to a vertex having lowest value of the field
+   * m_distanceFromRoot.  Remaining vertices are ordered according to 
+   * increasing distance.
+   *
+   * This method is provided in case the values of m_distanceFromRoot change
+   * during the routing calculations.
+   *
+   * @see SPFVertex
+   */
   void          Reorder (void);
 
 protected:
@@ -43,6 +136,18 @@ protected:
   CandidateList_t m_candidates;
 
 private:
+  /**
+   * Candidate Queue copy construction is disallowed (not implemented) to 
+   * prevent the compiler from slipping in incorrect versions that don't
+   * properly deal with deep copies.
+   */
+  CandidateQueue (CandidateQueue& sr);
+  /**
+   * Candidate Queue assignment operator is disallowed (not implemented) to
+   * prevent the compiler from slipping in incorrect versions that don't
+   * properly deal with deep copies.
+   */
+  CandidateQueue& operator= (CandidateQueue& sr);
 };
 
 } // namespace ns3
diff --git a/src/routing/static-router.h b/src/routing/static-router.h
index c863ddc90..1d7bf2ab3 100644
--- a/src/routing/static-router.h
+++ b/src/routing/static-router.h
@@ -282,6 +282,14 @@ protected:
   Ipv4Address m_routerId;
 
 private:
+  /**
+   * Static Router copy construction is disallowed.
+   */
+  StaticRouter (StaticRouter& sr);
+  /**
+   * Static Router copy assignment operator is disallowed.
+   */
+  StaticRouter& operator= (StaticRouter& sr);
 };
 
 } // namespace ns3