doxygen: fix warnings in network, mobility

src/mobility/examples/main-random-topology.cc

@@ -22,6 +22,11 @@
 
 using namespace ns3;
 
+/**
+ * Function called when there is a course change
+ * \param context event context
+ * \param position a pointer to the mobility model
+ */
 static void 
 CourseChange (std::string context, Ptr<const MobilityModel> position)
 {

src/mobility/examples/main-random-walk.cc

@@ -21,8 +21,13 @@
 
 using namespace ns3;
 
+/**
+ * Function called when there is a course change
+ * \param context event context
+ * \param mobility a pointer to the mobility model
+ */
 static void 
-CourseChange (std::string foo, Ptr<const MobilityModel> mobility)
+CourseChange (std::string context, Ptr<const MobilityModel> mobility)
 {
   Vector pos = mobility->GetPosition ();
   Vector vel = mobility->GetVelocity ();

src/mobility/helper/ns2-mobility-helper.cc

@@ -103,16 +103,22 @@ struct DestinationPoint
 
 /**
  * Parses a line of ns2 mobility
+ * \param str the string to parse
+ * \returns The parsed line
  */
 static ParseResult ParseNs2Line (const std::string& str);
 
 /** 
  * Put out blank spaces at the start and end of a line
+ * \param str input line
+ * \returns the line trimmed
  */
 static std::string TrimNs2Line (const std::string& str);
 
 /**
- * Checks if a string represents a number or it has others characters than digits an point.
+ * Checks if a string represents a number or it has others characters than digits and point.
+ * \param s the string to check
+ * \returns true if the string represents a number
  */
 static bool IsNumber (const std::string& s);
 
@@ -127,57 +133,91 @@ static bool IsVal (const std::string& str, T& ret);
 
 /**
  * Checks if the value between brackets is a correct nodeId number
+ * \param str string to check
+ * \returns true if the string represents a nodeId number
  */ 
 static bool HasNodeIdNumber (std::string str);
 
 /** 
  * Gets nodeId number in string format from the string like $node_(4)
+ * \param str string to de-tokenize
+ * \returns A string with the nodeId number
  */
 static std::string GetNodeIdFromToken (std::string str);
 
 /** 
  * Get node id number in int format
+ * \param pr the ParseResult to analyze
+ * \returns the node ID (as an int)
  */
 static int GetNodeIdInt (ParseResult pr);
 
 /**  
  * Get node id number in string format
+ * \param pr the ParseResult to analyze
+ * \returns the node ID (as a string)
  */
 static std::string GetNodeIdString (ParseResult pr);
 
 /**
  * Add one coord to a vector position
+ * \param actPos actual position (overwritten)
+ * \param coord coordinate (x, y, or z)
+ * \param value value of the coordinate
+ * \return The vector of the position
  */
 static Vector SetOneInitialCoord (Vector actPos, std::string& coord, double value);
 
 /** 
  * Check if this corresponds to a line like this: $node_(0) set X_ 123
+ * \param pr the ParseResult to analyze
+ * \returns true if the ParseResult looks like a coordinate without a scheduled time
  */
 static bool IsSetInitialPos (ParseResult pr);
 
 /** 
  * Check if this corresponds to a line like this: $ns_ at 1 "$node_(0) setdest 2 3 4"
+ * \param pr the ParseResult to analyze
+ * \returns true if the ParseResult looks like a coordinate with a scheduled time and destionation
  */
 static bool IsSchedSetPos (ParseResult pr);
 
 /**
  * Check if this corresponds to a line like this: $ns_ at 1 "$node_(0) set X_ 2"
+ * \param pr the ParseResult to analyze
+ * \returns true if the ParseResult looks like a coordinate with a scheduled time
  */
 static bool IsSchedMobilityPos (ParseResult pr);
 
 /**
  * Set waypoints and speed for movement.
+ * \param model mobility model
+ * \param lastPos last position
+ * \param at initial movement time
+ * \param xFinalPosition final position (X axis)
+ * \param yFinalPosition final position (Y axis)
+ * \param speed movement speed
+ * \returns A descriptor of the movement
  */
 static DestinationPoint SetMovement (Ptr<ConstantVelocityMobilityModel> model, Vector lastPos, double at,
                                      double xFinalPosition, double yFinalPosition, double speed);
 
 /**
  * Set initial position for a node
+ * \param model mobility model
+ * \param coord coordinate (x, y, or z)
+ * \param coordVal value of the coordinate
+ * \return The vector of the position
  */
 static Vector SetInitialPosition (Ptr<ConstantVelocityMobilityModel> model, std::string coord, double coordVal);
 
 /** 
  * Schedule a set of position for a node
+ * \param model mobility model
+ * \param at initial movement time
+ * \param coord coordinate (x, y, or z)
+ * \param coordVal value of the coordinate
+ * \return The vector of the position at the given time
  */
 static Vector SetSchedPosition (Ptr<ConstantVelocityMobilityModel> model, double at, std::string coord, double coordVal);
 

src/mobility/model/hierarchical-mobility-model.h

@@ -104,10 +104,12 @@ private:
 
   /**
    * Callback for when parent mobility model course change occurs
+   * \param model mobility mode (unused)
    */
   void ParentChanged (Ptr<const MobilityModel> model);
   /**
    * Callback for when child mobility model course change occurs
+   * \param model mobility mode (unused)
    */
   void ChildChanged (Ptr<const MobilityModel> model);
 

src/mobility/model/position-allocator.h

@@ -88,7 +88,7 @@ public:
    * \brief Add the positions listed in a file.
    * The file should be a simple text file, with one position per line,
    * either X and Y, or X, Y and Z, in meters.  The delimiter can
-   * be any character, such as ',' or '\t'; the default is a comma ','.
+   * be any character, such as ',' or '\\t'; the default is a comma ','.
    *
    * The file is read using CsvReader, which explains how comments
    * and whitespace are handled.

src/mobility/model/random-walk-2d-mobility-model.h

@@ -66,6 +66,7 @@ private:
   /**
    * Walk according to position and velocity, until distance is reached,
    * time is reached, or intersection with the bounding box
+   * \param timeLeft The remaining time of the walk
    */
   void DoWalk (Time timeLeft);
   /**

src/mobility/model/waypoint-mobility-model.h

@@ -111,12 +111,14 @@ public:
 
   /**
    * Get the waypoint that this object is traveling towards.
+   * \returns The waypoint
    */
   Waypoint GetNextWaypoint (void) const;
 
   /**
    * Get the number of waypoints left for this object, excluding
    * the next one.
+   * \returns The number of waypoints left
    */
   uint32_t WaypointsLeft (void) const;
 

src/mobility/test/ns2-mobility-helper-test-suite.cc

@@ -109,7 +109,11 @@ public:
         vel (v)
     {
     }
-    /// Sort by timestamp
+    /**
+     * Less-than operator - used to sort by timestamp
+     * \param o object to compare to
+     * \returns true if the timestamp of the 1nd operand is less than the other one's
+     */
     bool operator< (ReferencePoint const & o) const
     {
       return (time < o.time);
@@ -133,17 +137,29 @@ public:
   virtual ~Ns2MobilityHelperTest ()
   {
   }
-  /// Set NS-2 trace to read as single large string (don't forget to add \\n and quote \"'s)
+  /**
+   * Set NS-2 trace to read as single large string (don't forget to add \\n and quote \"'s)
+   *  \param trace the mobility trace
+   */
   void SetTrace (std::string const & trace)
   {
     m_trace = trace;
   }
-  /// Add next reference point
+  /**
+   * Add next reference point
+   * \param r reference point to add
+   */
   void AddReferencePoint (ReferencePoint const & r)
   {
     m_reference.push_back (r);
   }
-  /// Sugar
+  /**
+   * Add next reference point
+   * \param id reference point id
+   * \param sec reference point ime (in seconds)
+   * \param p reference point position
+   * \param v reference point velocity
+   */
   void AddReferencePoint (const char * id, double sec, Vector const & p, Vector const & v)
   {
     AddReferencePoint (ReferencePoint (id, Seconds (sec), p, v));
@@ -164,7 +180,10 @@ private:
   std::string m_traceFile;
 
 private:
-  /// Dump NS-2 trace to tmp file
+  /**
+   * Dump NS-2 trace to tmp file
+   * \return true on error.
+   */
   bool WriteTrace ()
   {
     m_traceFile = CreateTempDirFilename ("Ns2MobilityHelperTest.tcl");
@@ -186,7 +205,10 @@ private:
         Names::Add (os.str (), nodes.Get (i));
       }
   }
-  /// Check that all initial positions are correct
+  /**
+   * Check that all initial positions are correct
+   * \return true on error.
+   */
   bool CheckInitialPositions ()
   {
     std::stable_sort (m_reference.begin (), m_reference.end ());
@@ -206,7 +228,11 @@ private:
       }
     return IsStatusFailure ();
   }
-  /// Listen for course change events
+  /**
+   * Listen for course change events
+   * \param context event context
+   * \param mobility a pointer to the mobility model
+   */
   void CourseChange (std::string context, Ptr<const MobilityModel> mobility)
   {
     Time time = Simulator::Now ();

src/network/helper/delay-jitter-estimation.h

@@ -30,7 +30,7 @@ namespace ns3 {
  *
  * \brief Quick and dirty delay and jitter estimation,
  * implementing the jitter algorithm originally from
- * \RFC{1889} (RTP), and unchanged in \RFC(3550) 
+ * \RFC{1889} (RTP), and unchanged in \RFC{3550}
  *
  * This implementation uses the integer variant of the algorithm
  * given in RFC 1889 Appendix A.8 ,p. 71, and repeated in

src/network/test/packet-test-suite.cc

@@ -449,6 +449,14 @@ private:
    * \param ... The variable arguments
    */
   void DoCheck (Ptr<const Packet> p, const char *file, int line, uint32_t n, ...);
+  /**
+   * Checks the packet and its data
+   * \param p The packet
+   * \param file The file name
+   * \param line The line number
+   * \param n The number of variable arguments
+   * \param ... The variable arguments
+   */
   void DoCheckData (Ptr<const Packet> p, const char *file, int line, uint32_t n, ...);
 };
 

src/network/test/test-data-rate.cc

@@ -25,12 +25,36 @@
 
 using namespace ns3;
 
+/**
+ * \ingroup network-test
+ * \ingroup tests
+ *
+ * \brief Test Data rate
+ *
+ */
 class DataRateTestCase : public TestCase
 {
 public:
+  /**
+   * Constructor
+   * \param name test name
+   */
   DataRateTestCase (std::string name);
   virtual ~DataRateTestCase ();
+
+  /**
+   * Checks if two time values are equal
+   * \param t1 first time to check
+   * \param t2 second time to check
+   * \param msg check output message
+   */
   void CheckTimesEqual (Time t1, Time t2, const std::string msg);
+  /**
+   * Checks if two data rates values are equal
+   * \param d1 first data rate to check
+   * \param d2 second data rate to check
+   * \param msg check output message
+   */
   void CheckDataRateEqual (DataRate d1, DataRate d2, const std::string msg);
 
 protected:
@@ -59,10 +83,25 @@ DataRateTestCase::CheckDataRateEqual (DataRate d1, DataRate d2, const std::strin
   NS_TEST_EXPECT_MSG_EQ (d1, d2, msg);
 }
 
+/**
+ * \ingroup network-test
+ * \ingroup tests
+ *
+ * \brief Test Data rate
+ *
+ */
 class DataRateTestCase1 : public DataRateTestCase
 {
 public:
   DataRateTestCase1 ();
+
+  /**
+   * Checks that a given number of bits, at a specified datarate, are
+   * corresponding to a given time
+   * \param rate the DataRate
+   * \param nBits number of bits
+   * \param correctTime expected time
+   */
   void SingleTest (std::string rate, size_t nBits, Time correctTime);
 
 private:
@@ -114,13 +153,44 @@ DataRateTestCase1::DoRun ()
     }
 }
 
+/**
+ * \ingroup network-test
+ * \ingroup tests
+ *
+ * \brief Test Data rate
+ *
+ */
 class DataRateTestCase2 : public DataRateTestCase
 {
 public:
   DataRateTestCase2 (); 
+  /**
+   * Checks data rate addition
+   * \param rate1 first data rate
+   * \param rate2 second data rate
+   * \param rate3 third data rate (first plus second)
+   */
   void AdditionTest (std::string rate1, std::string rate2, std::string rate3);
+  /**
+   * Checks data rate subtraction
+   * \param rate1 first data rate
+   * \param rate2 second data rate
+   * \param rate3 third data rate (first minus second)
+   */
   void SubtractionTest (std::string rate1, std::string rate2, std::string rate3);
+  /**
+   * Checks data rate integer multiplication
+   * \param rate1 first data rate
+   * \param factor multiplication factor
+   * \param rate2 second data rate  (first multiplied by factor)
+   */
   void MultiplicationIntTest (std::string rate1, uint64_t factor, std::string rate2);
+  /**
+   * Checks data rate floating point multiplication
+   * \param rate1 first data rate
+   * \param factor multiplication factor
+   * \param rate2 second data rate  (first multiplied by factor)
+   */
   void MultiplicationDoubleTest (std::string rate1, double factor, std::string rate2);
 
 private:
@@ -139,10 +209,10 @@ DataRateTestCase2::AdditionTest (std::string rate1, std::string rate2, std::stri
   DataRate dr2 (rate2);
   DataRate dr3 (rate3);
 
-  CheckDataRateEqual(dr1 + dr2, dr3, "DataRate Additon returned incorrect value");
+  CheckDataRateEqual(dr1 + dr2, dr3, "DataRate Addition returned incorrect value");
   
   dr1 += dr2;
-  CheckDataRateEqual(dr1, dr3, "DataRate Additon returned incorrect value");
+  CheckDataRateEqual(dr1, dr3, "DataRate Addition returned incorrect value");
 }
 
 void
@@ -195,6 +265,12 @@ DataRateTestCase2::DoRun ()
   MultiplicationDoubleTest("6Gb/s", 1.0/7.0, "857142857.14b/s");
 }
 
+/**
+ * \ingroup network-test
+ * \ingroup tests
+ *
+ * \brief DataRate TestSuite
+ */
 class DataRateTestSuite : public TestSuite
 {
 public:
@@ -207,5 +283,4 @@ DataRateTestSuite::DataRateTestSuite () : TestSuite ("data-rate", UNIT)
   AddTestCase (new DataRateTestCase2 (), TestCase::QUICK);
 }
 
-// Do not forget to allocate an instance of this TestSuite
-static DataRateTestSuite sDataRateTestSuite;
+static DataRateTestSuite sDataRateTestSuite; //!< Static variable for test initialization

src/network/utils/data-rate.h

@@ -121,28 +121,28 @@ public:
   /**
    * \return the DataRate representing the sum of this object with rhs
    * 
-   * \param the DataRate to add to this DataRate
+   * \param rhs the DataRate to add to this DataRate
    */
   DataRate operator + (DataRate rhs);
 
   /**
    * \return the DataRate representing the sum of this object with rhs
    * 
-   * \param the DataRate to add to this DataRate
+   * \param rhs the DataRate to add to this DataRate
    */
   DataRate& operator += (DataRate rhs);
 
   /**
    * \return the DataRate representing the difference of this object with rhs
    * 
-   * \param the DataRate to subtract from this DataRate
+   * \param rhs the DataRate to subtract from this DataRate
    */
   DataRate operator - (DataRate rhs);
 
   /**
    * \return the DataRate representing the difference of this object with rhs
    * 
-   * \param the DataRate to subtract from this DataRate
+   * \param rhs the DataRate to subtract from this DataRate
    */
   DataRate& operator -= (DataRate rhs);
 

src/network/utils/ipv4-address.cc

@@ -197,6 +197,10 @@ Ipv4Mask::GetPrefixLength (void) const
   return tmp; 
 }
 
+/**
+ *  Value of a not-yet-initialized IPv4 address, corresponding to 102.102.102.102.
+ *  This is totally arbitrary.
+ */
 static constexpr uint32_t UNINITIALIZED = 0x66666666U;
 
 Ipv4Address::Ipv4Address ()

src/network/utils/ipv4-address.h

@@ -396,35 +396,16 @@ std::istream & operator >> (std::istream &is, Ipv4Address &address);
  */
 std::istream & operator >> (std::istream &is, Ipv4Mask &mask);
 
-/**
- * \brief Equal to operator.
- *
- * \param a the first operand
- * \param b the first operand
- * \returns true if the operands are equal
- */
 inline bool operator == (const Ipv4Address &a, const Ipv4Address &b)
 {
   return (a.m_address == b.m_address);
 }
-/**
- * \brief Not equal to operator.
- *
- * \param a the first operand
- * \param b the first operand
- * \returns true if the operands are not equal
- */
+
 inline bool operator != (const Ipv4Address &a, const Ipv4Address &b)
 {
   return (a.m_address != b.m_address);
 }
-/**
- * \brief Less than operator.
- *
- * \param a the first operand
- * \param b the first operand
- * \returns true if the operand a is less than operand b
- */
+
 inline bool operator < (const Ipv4Address &a, const Ipv4Address &b)
 {
   return (a.m_address < b.m_address);
@@ -448,25 +429,11 @@ public:
   size_t operator() (Ipv4Address const &x) const;
 };
 
-/**
- * \brief Equal to operator.
- *
- * \param a the first operand
- * \param b the first operand
- * \returns true if the operands are equal
- */
 inline bool operator == (Ipv4Mask const &a, Ipv4Mask const &b)
 {
   return (a.m_mask == b.m_mask);
 }
 
-/**
- * \brief Not equal to operator.
- *
- * \param a the first operand
- * \param b the first operand
- * \returns true if the operands are not equal
- */
 inline bool operator != (Ipv4Mask const &a, Ipv4Mask const &b)
 {
   return (a.m_mask != b.m_mask);

src/network/utils/ipv6-address.h

@@ -406,7 +406,6 @@ public:
   /**
    * \brief Get the bytes corresponding to the address.
    * \param buf buffer to store the data
-   * \return bytes of the address
    */
   void GetBytes (uint8_t buf[16]) const;
 

src/network/utils/lollipop-counter.h

@@ -136,7 +136,7 @@ public:
   }
 
   /**
-   * Checks if two counters are comparable (i.e., not desynchronized).
+   * Checks if the counter is comparable with another counter (i.e., not desynchronized).
    *
    * If the absolute magnitude of difference of the two
    * sequence counters is greater than Sequence Window, then a
@@ -146,7 +146,8 @@ public:
    * Sequence Window is equal to 2^N where N is (by default) half the number
    * of digits of the underlying type.
    *
-   * \returns true if the two counters are comparable.
+   * \param val counter to compare
+   * \returns true if the counters are comparable.
    */
   bool IsComparable (const LollipopCounter &val) const
   {

src/network/utils/mac16-address.h

@@ -110,6 +110,7 @@ public:
    * bits 3-7 within DST[15].  The initial 3-bit pattern of "100" follows
    * the 16-bit address format for multicast addresses (Section 12).
    *
+   * \param address base IPv6 address
    * \returns the multicast 16-bit address.
    */
 

src/network/utils/pcap-file.h

@@ -111,8 +111,6 @@ public:
    * \param nanosecMode Flag indicating the time resolution of the writing
    * system. Default to false.
    *
-   * \return false if the open succeeds, true otherwise.
-   *
    * \warning Calling this method on an existing file will result in the loss
    * any existing data.
    */

src/network/utils/radiotap-header.cc

@@ -872,11 +872,11 @@ RadiotapHeader::SetHeMuFields (uint16_t flags1, uint16_t flags2, const std::arra
 }
 
 void
-RadiotapHeader::SetHeMuPerUserFields (uint16_t per_user_1, uint16_t per_user_2, uint8_t perUserPosition, uint8_t perUserKnown)
+RadiotapHeader::SetHeMuPerUserFields (uint16_t perUser1, uint16_t perUser2, uint8_t perUserPosition, uint8_t perUserKnown)
 {
-  NS_LOG_FUNCTION (this << per_user_1 << per_user_2 << +perUserPosition << +perUserKnown);
-  m_heMuPerUser1 = per_user_1;
-  m_heMuPerUser2 = per_user_2;
+  NS_LOG_FUNCTION (this << perUser1 << perUser2 << +perUserPosition << +perUserKnown);
+  m_heMuPerUser1 = perUser1;
+  m_heMuPerUser2 = perUser2;
   m_heMuPerUserPosition = perUserPosition;
   m_heMuPerUserKnown = perUserKnown;
   if (!(m_present & RADIOTAP_HE_MU_OTHER_USER))

src/network/utils/radiotap-header.h

@@ -429,7 +429,7 @@ public:
    * @param perUserPosition The per_user_position field.
    * @param perUserKnown The per_user_known field.
    */
-  void SetHeMuPerUserFields (uint16_t per_user_1, uint16_t per_user_2, uint8_t perUserPosition, uint8_t perUserKnown);
+  void SetHeMuPerUserFields (uint16_t perUser1, uint16_t perUser2, uint8_t perUserPosition, uint8_t perUserKnown);
 
 private:
   /**