Update doxygen documentation

model/isl-mock-channel.h

@@ -35,33 +35,51 @@
 #include "mock-net-device.h"
 #include "mock-channel.h"
 
+/**
+ * \file
+ * \ingroup leo
+ * IslMockChannel declaration
+ */
+
 namespace ns3 {
 
 class MockNetDevice;
 
 /**
- * \ingroup network
- * \defgroup channel Channel
- */
-/**
- * \ingroup channel
- * \brief Simplified inter-satellite channel
+ * \ingroup leo
+ * \brief Simplified model of an inter-satellite channel
  *
- * A perfect channel with varariable delay (time-of-flight).
+ * This channel distributes packets to all attached devies to which the sender has a line-of-sight.
+ * It is typically used in conjunction with the IslPropagationLossModel and ConstantSpeedPropagationDelay.
  *
  */
 class IslMockChannel : public MockChannel
 {
 public:
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
 
+  /// constructor
   IslMockChannel ();
+  /// destructor
   virtual ~IslMockChannel ();
 
+  /**
+   * \brief Starts a transmission of a packet
+   * \return true iff the transmission was successful
+   * \param p the packet to transmit
+   * \param devId the id of the sender device as an index into the attached
+   * devices
+   * \param dst the destination address
+   * \param txTime the transmission delay of the packet
+   */
   bool TransmitStart (Ptr<const Packet> p, uint32_t devId, Address dst, Time txTime);
 
 private:
-  std::vector<Ptr<MockNetDevice> > m_link;
+  std::vector<Ptr<MockNetDevice> > m_link; ///< Attached devices
 
 
 }; // class MockChannel

model/isl-propagation-loss-model.h

@@ -22,25 +22,44 @@
 #include <ns3/object.h>
 #include <ns3/propagation-loss-model.h>
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of IslPropagationLossModel
+ */
+
 #define LEO_EARTH_RAD 6.371009e6
 
 namespace ns3 {
 
+/**
+ * \ingroup leo
+ * \brief An approximate model for the propagation loss between any two low
+ * earth orbit satellites using the line-of-sight
+ *
+ */
 class IslPropagationLossModel : public PropagationLossModel
 {
 public:
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+  /// constructor
   IslPropagationLossModel ();
+  /// destructor
   virtual ~IslPropagationLossModel ();
 
   /**
-   * true if there is at least one intersection of ISL line-of-sight with earth
-   * (LOS is blocked by earth)
+   * \brief Check if there is a direc line-of-sight between the two points
    *
-   * Assumes earth is sperical.
+   * Assumes earth is spherical.
    *
-   * \param a first node
-   * \param b second node
+   * \param a first point
+   * \param b second point
+   * \return true iff there is a line-of-sight between the points
    */
   static bool GetLos (Ptr<MobilityModel> a, Ptr<MobilityModel> b);
 private:
@@ -56,10 +75,7 @@ private:
   virtual double DoCalcRxPower (double txPowerDbm,
                                 Ptr<MobilityModel> a,
                                 Ptr<MobilityModel> b) const;
-  /**
-   * Subclasses must implement this; those not using random variables
-   * can return zero
-   */
+
   virtual int64_t DoAssignStreams (int64_t stream);
 };
 

model/leo-circular-orbit-mobility-model.h

@@ -25,6 +25,13 @@
 #include "ns3/mobility-model.h"
 #include "ns3/nstime.h"
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of LeoCircularOrbitMobilityModel
+ */
+
 #define LEO_EARTH_RAD_KM 6371.0090
 #define LEO_EARTH_GM_KM_E10 39.8600436
 
@@ -41,22 +48,42 @@ class LeoCircularOrbitMobilityModel : public MobilityModel
 {
 public:
   /**
-   * Register this type with the TypeId system.
+   * \brief Get the type ID.
    * \return the object TypeId
    */
   static TypeId GetTypeId (void);
+  /// constructor
   LeoCircularOrbitMobilityModel ();
+  /// destructor
   virtual ~LeoCircularOrbitMobilityModel ();
 
   /**
-   * km/s
+   * \brief Gets the speed of the node
+   * \return the speed in m/s
    */
   double GetSpeed () const;
 
+  /**
+   * \brief Gets the altitude
+   * \return the altitude
+   */
   double GetAltitude () const;
+  /**
+   * \brief Sets the altitude
+   * \param the altitude
+   */
   void SetAltitude (double h);
 
+  /**
+   * \brief Gets the inclination
+   * \return the inclination
+   */
   double GetInclination () const;
+
+  /**
+   * \brief Sets the inclination
+   * \param the inclination
+   */
   void SetInclination (double incl);
 
 private:
@@ -105,30 +132,46 @@ private:
   virtual Vector DoGetVelocity (void) const;
 
   /**
-   * Get the normal vector of the orbital plane
+   * \brief Get the normal vector of the orbital plane
    */
   Vector3D PlaneNorm () const;
 
+  /**
+   * \brief Gets the distance the satellite has progressed from its original
+   * position at time t in rad
+   *
+   * \param t a point in time
+   * \return distance in rad
+   */
   double GetProgress (Time t) const;
 
   /**
-   * Advances a satellite by a degrees on the orbital plane
+   * \brief Advances a satellite by a degrees inside the orbital plane
+   * \param a angle by which to rotate
+   * \param x vector to rotate
+   * \return rotated vector
    */
   Vector3D RotatePlane (double a, const Vector3D &x) const;
 
   /**
-   * Calculate the position at time
-   *
+   * \brief Calculate the position at time t
    * \param t time
+   * \return position at time t
    */
   Vector CalcPosition (Time t) const;
 
   /**
-   * Calc the latitude depending on simulation time inside ITRF coordinate
+   * \brief Calc the latitude depending on simulation time inside ITRF coordinate
    * system
+   *
+   * \return latitude
    */
   double CalcLatitude () const;
 
+  /**
+   * \brief Update the internal position of the mobility model
+   * \return position that will be returned upon next call to DoGetPosition
+   */
   Vector Update ();
 };
 

model/leo-circular-orbit-position-allocator.h

@@ -21,32 +21,54 @@
 
 #include "ns3/position-allocator.h"
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of LeoCircularOrbitAllocator
+ */
+
 namespace ns3 {
 
 /**
- * \brief Allocate pairs of latitude and longitude (offset within orbit) for
+ * \ingroup leo
+ * \brief Allocate pairs of longitude and latitude (offset within orbit) for
  * use in LeoCircularOrbitMobilityModel
  */
 class LeoCircularOrbitAllocator : public PositionAllocator
 {
 public:
   /**
-   * Register this type with the TypeId system.
+   * \brief Get the type ID.
    * \return the object TypeId
    */
   static TypeId GetTypeId ();
 
+  /// constructor
   LeoCircularOrbitAllocator ();
+  /// destructor
   virtual ~LeoCircularOrbitAllocator ();
 
+  /**
+   * \brief Gets the next position on the latitude longitude grid
+   *
+   * If all positions have been returned once, the first position is returned
+   * again and so on.
+   *
+   * \return the next latitude, longitude pair
+   */
   virtual Vector GetNext (void) const;
   virtual int64_t AssignStreams (int64_t stream);
 
 private:
+  /// Number of orbits two distribute the satellites on
   uint64_t m_numOrbits;
+  /// Number of satellites per orbit
   uint64_t m_numSatellites;
 
+  /// The last orit that has been assigned
   mutable uint64_t m_lastOrbit;
+  /// The last position inside the orbit that has been assigned
   mutable uint64_t m_lastSatellite;
 };
 

model/leo-lat-long.h

@@ -21,20 +21,47 @@
 
 #include <iostream>
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of LeoLatLong
+ */
+
 namespace ns3 {
 
+/**
+ * \brief Wrapper around a pair of latitude and longitude
+ */
 class LeoLatLong
 {
 public:
+  /// constructor
   LeoLatLong ();
+  /// destructor
   LeoLatLong (double latitude, double longitude);
   virtual ~LeoLatLong();
 
+  /// Latitude
   double latitude;
+  /// Longitude
   double longitude;
 };
 
+/**
+ * \brief Serialize the LeoLatLong instance using a colon as a separator
+ * \param os stream to serialize into
+ * \param latLong to serialize
+ * \return returns the stream
+ */
 std::ostream &operator << (std::ostream &os, const LeoLatLong &latLong);
+
+/**
+ * \brief Deserialize the LeoLatLong instance using a colon as a separator
+ * \param is stream to deserialize from
+ * \param latLong to deserialize into
+ * \return returns the stream
+ */
 std::istream &operator >> (std::istream &is, LeoLatLong &latLong);
 
 };

model/leo-mock-channel.h

@@ -34,29 +34,42 @@
 #include "ns3/propagation-loss-model.h"
 #include "mock-channel.h"
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of LeoMockChannl
+ */
+
 namespace ns3 {
 
 /**
  * \ingroup leo
- * \defgroup channel Channel
- */
-/**
- * \ingroup channel
- * \brief Mocked satellite-gateway, satellite-terminal channel types
+ * \brief Channel between satellite and gateway
  *
+ * Delivers packets to all attached devices on opposing site (satellite to
+ * gateway and vice-versa)
+ *
+ * Usually used together with LeoPropagationLossModel and LeoPropagationDelay.
  */
 class LeoMockChannel : public MockChannel
 {
 public:
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
 
+  /// constructor
   LeoMockChannel ();
+  /// destructor
   virtual ~LeoMockChannel ();
 
   /**
    * \see MockChannel::TransmitStart
    *
-   * A packet is transmitted if the destination is reachable via the beam.
+   * \brief A packet is transmitted if the destination is reachable via the beam.
    */
   virtual bool TransmitStart (Ptr<const Packet> p, uint32_t devId, Address dst, Time txTime);
 
@@ -71,7 +84,11 @@ private:
    * type (no sat-sat or ground-ground).
    */
   typedef std::map<Address, Ptr<MockNetDevice> > DeviceIndex;
+
+  /// Devices that are on the ground (gateways)
   DeviceIndex m_groundDevices;
+
+  /// Devices that are in space (satellites)
   DeviceIndex m_satelliteDevices;
 }; // class MockChannel
 

model/leo-mock-net-device.h

@@ -21,37 +21,66 @@
 
 #include "mock-net-device.h"
 
+/**
+ * \file
+ * \ingroup leo
+ */
+
 namespace ns3
 {
-  /**
-   * \brief A mocked satellite-ground link communication device with a type
-   */
+/**
+ * \ingroup leo
+ * \brief A satellite-ground communication device with a type
+ */
 class LeoMockNetDevice : public MockNetDevice
 {
 public:
+  /**
+   * \brief Type of the device. Can either be on ground or in space.
+   */
   enum DeviceType
   {
+    /// Device is on the ground
     GND,
+    /// Device is in space
     SAT
   };
 
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
 
+  /// constructor
   LeoMockNetDevice ();
 
+  /// destructor
   virtual ~LeoMockNetDevice ()
   {
   }
 
+  /**
+   * \brief Get the type of this device
+   * \return device type
+   */
   DeviceType GetDeviceType () const;
+
+  /**
+   * \brief Set the type of this device
+   * \return device type
+   */
   void SetDeviceType (DeviceType deviceType);
 
 protected:
   virtual double DoCalcRxPower (double rxPower) const;
 
 private:
+  /// Device type
   DeviceType m_deviceType;
+  /// Receiver loss
   double m_rxLoss;
+  /// Receiver gain
   double m_rxGain;
 };
 

model/leo-oneweb-constants.h

@@ -19,18 +19,17 @@
 #ifndef LEO_ONEWEB_CONSTANTS
 #define LEO_ONEWEB_CONSTANTS
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of constants
+ */
+
 namespace ns3 {
 
 /**
  * \ingroup leo
- * \defgroup constants Channel
- */
-/**
- * \ingroup constants
- * \defgroup oneweb
- */
-/**
- * \ingroup oneweb
  * \brief Constants for oneweb network estimated from channel parameters
  *
  * Source http://systemarchitect.mit.edu/docs/delportillo18b.pdf

model/leo-orbit.h

@@ -21,21 +21,56 @@
 
 #include "ns3/uinteger.h"
 
+/**
+ * \file
+ * \ingroup leo
+ */
+
 namespace ns3
 {
 class LeoOrbit;
 
+/**
+ * \brief Serialize an orbit
+ * \return the stream
+ * \param os the stream
+ * \param [in] orbit is an Orbit
+ */
 std::ostream &operator << (std::ostream &os, const LeoOrbit &orbit);
+
+/**
+ * \brief Deserialize an orbit
+ * \return the stream
+ * \param is the stream
+ * \param [out] orbit is the Orbit
+ */
 std::istream &operator >> (std::istream &is, LeoOrbit &orbit);
 
+/**
+ * \ingroup leo
+ * \brief Orbit definition
+ */
 class LeoOrbit {
 public:
+  /// constructor
   LeoOrbit ();
+  /**
+   * \brief Constructor
+   * \param a altitude
+   * \param i inclination
+   * \param p number planes
+   * \param s number of satellites in plane
+   */
   LeoOrbit (double a, double i, double p, double s) : alt (a), inc (i), planes (p), sats (s) {}
+  /// destructor
   virtual ~LeoOrbit ();
+  /// Altitude of orbit
   double alt;
+  /// Inclination of orbit
   double inc;
+  /// Number of planes with that altitude and inclination
   uint16_t planes;
+  /// Number of satellites in those planes
   uint16_t sats;
 };
 

model/leo-polar-position-allocator.h

@@ -23,31 +23,45 @@
 
 #define LEO_GND_RAD_EARTH 6.371e6
 
+/**
+ * \file
+ * \ingroup leo
+ *
+ * Declaration of LeoPolarPositionAllocator
+ */
+
 namespace ns3 {
 
 /**
- * \brief Allocate pairs of latitude and longitude.
+ * \ingroup leo
+ * \brief Allocator for pairs of latitude and longitude.
  */
 class LeoPolarPositionAllocator : public PositionAllocator
 {
 public:
   /**
-   * Register this type with the TypeId system.
+   * \brief Get the type ID.
    * \return the object TypeId
    */
   static TypeId GetTypeId ();
 
+  /// constructor
   LeoPolarPositionAllocator ();
+  /// desctructor
   virtual ~LeoPolarPositionAllocator ();
 
   virtual Vector GetNext (void) const;
   virtual int64_t AssignStreams (int64_t stream);
 
 private:
+  /// Number of latitudial positions
   uint32_t m_latNum;
+  /// Number of longitudinal positions
   uint32_t m_lonNum;
 
+  /// Current latitudinal position
   mutable uint32_t m_lat;
+  /// Current longitudinal position
   mutable uint32_t m_lon;
 };
 

model/leo-propagation-loss-model.h

@@ -25,13 +25,30 @@
 #define LEO_PROP_EARTH_RAD 6.37101e6
 #define LEO_SPEED_OF_LIGHT_IN_AIR 299702458
 
+/**
+ * \file
+ * \ingroup leo
+ * Declaration of LeoPropagationLossModel
+ */
+
 namespace ns3 {
 
+/**
+ * \ingroup leo
+ * \brief Propagation loss model for transmissions between satellites and
+ * gateways
+ */
 class LeoPropagationLossModel : public PropagationLossModel
 {
 public:
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
+  /// constructor
   LeoPropagationLossModel ();
+  /// destructor
   virtual ~LeoPropagationLossModel ();
 
 private:
@@ -57,9 +74,7 @@ private:
   double m_linkMargin;
 
   /**
-   * Returns the Rx Power taking into account only the particular
-   * PropagationLossModel.
-   *
+   * \brief Calculate the Rx Power
    * \param txPowerDbm current transmission power (in dBm)
    * \param a the mobility model of the source
    * \param b the mobility model of the destination
@@ -68,15 +83,26 @@ private:
   virtual double DoCalcRxPower (double txPowerDbm,
                                 Ptr<MobilityModel> a,
                                 Ptr<MobilityModel> b) const;
-  /**
-   * Subclasses must implement this; those not using random variables
-   * can return zero
-   */
+
   virtual int64_t DoAssignStreams (int64_t stream);
 
+  /**
+   * \brief Set the elevation angle
+   * \param angle elevation
+   */
   void SetElevationAngle (double angle);
+
+  /**
+   * \brief Get the elevation angle
+   * \return elevation angle
+   */
   double GetElevationAngle () const;
 
+  /**
+   * \brief Get the maximum communication distance for satellite
+   * \param sat satellite
+   * \return distance
+   */
   double GetCutoffDistance (const Ptr<MobilityModel> sat) const;
 };
 

model/leo-starlink-constants.h

@@ -19,18 +19,16 @@
 #ifndef LEO_STARLINK_CONSTANTS
 #define LEO_STARLINK_CONSTANTS
 
+/**
+ * \file
+ * \ingroup leo
+ * Definition of Starlink link constants
+ */
+
 namespace ns3 {
 
 /**
  * \ingroup leo
- * \defgroup constants Channel
- */
-/**
- * \ingroup constants
- * \defgroup starlink
- */
-/**
- * \ingroup starlink
  * \brief Constants for starlink network estimated from channel parameters
  *
  * Source http://systemarchitect.mit.edu/docs/delportillo18b.pdf

model/leo-telesat-constants.h

@@ -19,18 +19,16 @@
 #ifndef LEO_TELESAT_CONSTANTS
 #define LEO_TELESAT_CONSTANTS
 
+/**
+ * \file
+ * \ingroup leo
+ * Definition of Telesat link constants
+ */
+
 namespace ns3 {
 
 /**
  * \ingroup leo
- * \defgroup constants Channel
- */
-/**
- * \ingroup constants
- * \defgroup telesat
- */
-/**
- * \ingroup starlink
  * \brief Constants for Telesat network estimated from channel parameters
  *
  * Source http://systemarchitect.mit.edu/docs/delportillo18b.pdf

model/mock-channel.h

@@ -34,27 +34,39 @@
 #include "ns3/propagation-loss-model.h"
 #include "mock-net-device.h"
 
+/**
+ * \file
+ * \ingroup leo
+ * Declaration of class MockNetDevice
+ */
+
 namespace ns3 {
 
 class MockNetDevice;
 
 /**
- * \ingroup network
- * \defgroup channel Channel
- */
-/**
- * \ingroup channel
- * \brief Mocked channel
- *
+ * \ingroup leo
+ * \brief Base class for LeoMockChannel and IslMockChannel
  */
 class MockChannel : public Channel
 {
 public:
+  /**
+   * \brief Get the type ID.
+   * \return the object TypeId
+   */
   static TypeId GetTypeId (void);
 
+  /// constructor
   MockChannel ();
+  /// destructor
   virtual ~MockChannel ();
 
+  /**
+   * \brief Get device at index i
+   * \param i index
+   * \return pointer to device
+   */
   Ptr<NetDevice> GetDevice (std::size_t i) const;
 
   /**
@@ -71,13 +83,41 @@ public:
    */
   virtual bool Detach (uint32_t deviceId);
 
+  /**
+   * \brief Get number of devices in channel
+   * \return number of devices
+   */
   std::size_t GetNDevices (void) const;
+
+  /**
+   * \brief Start to transmit a packet
+   *
+   * Subclasses must implement this.
+   */
   virtual bool TransmitStart (Ptr<const Packet> p, uint32_t devId, Address dst, Time txTime) = 0;
 
+  /**
+   * \brief Get the propagation loss model
+   * \return propagation loss in dBm
+   */
   Ptr<PropagationLossModel> GetPropagationLoss (void) const;
+
+  /**
+   * \brief Set the propagation loss model
+   * \param model propagation loss
+   */
   void SetPropagationLoss (Ptr<PropagationLossModel> model);
 
+  /**
+   * \brief Get the propagation delay model
+   * \return propagation delay
+   */
   Ptr<PropagationDelayModel> GetPropagationDelay (void) const;
+
+  /**
+   * \brief Set the propagation delay model
+   * \param delay propagation delay
+   */
   void SetPropagationDelay (Ptr<PropagationDelayModel> delay);
 
 protected:
@@ -90,25 +130,39 @@ protected:
 
   /**
    * \brief Get the propagation delay associated with this channel
+   * \param first mobility model
+   * \param second mobility model
+   * \param txTime time of the transmission
    * \returns Propagation time delay
    */
   Time GetPropagationDelay (Ptr<MobilityModel> first, Ptr<MobilityModel> second, Time txTime) const;
 
+  /**
+   * \brief Get a device by it's address
+   * \param addr address of the device
+   * \return pointer to the device if it is attached to the channel, null otherwise
+   */
   Ptr<MockNetDevice> GetDevice (Address &addr) const;
 
+  /**
+   * \brief Deliver a packet to a destination
+   * \param p packet
+   * \param src source of a packet
+   * \param dst destination of a packet
+   * \param txTime transmission time of the packet
+   * \return true iff the transmission has been successful
+   */
   bool Deliver ( Ptr<const Packet> p, Ptr<MockNetDevice> src, Ptr<MockNetDevice> dst, Time txTime);
 
 private:
 
+  /// All devices that are attached to the channel
   std::vector<Ptr<MockNetDevice> > m_link;
 
-  /**
-   * \brief Propagation delay model to be used with this channel
-   */
+  /// Propagation delay model to be used with this channel
   Ptr<PropagationDelayModel> m_propagationDelay;
-  /**
-   * \brief Propagation loss model to be used with this channel
-   */
+
+  /// Propagation loss model to be used with this channel
   Ptr<PropagationLossModel> m_propagationLoss;
 
 }; // class MockChannel

model/mock-net-device.h

@@ -33,6 +33,15 @@
 #include "ns3/mac48-address.h"
 #include "ns3/mobility-model.h"
 
+/**
+ * \file
+ * \ingroup leo
+ * Declares MockNetDevice
+ *
+ * Lots of stuff copied and adapted from PointToPointNetDevice and
+ * CsmaNetDevice
+ */
+
 namespace ns3 {
 
 template <typename Item> class Queue;
@@ -40,6 +49,10 @@ class NetDeviceQueueInterface;
 class MockChannel;
 class ErrorModel;
 
+/**
+ * \ingroup leo
+ * \brief Network device for use with MockChannel
+ */
 class MockNetDevice : public NetDevice
 {
 public:
@@ -492,4 +505,4 @@ private:
 
 } // namespace ns3
 
-#endif /* ISL_NET_DEVICE_H */
+#endif /* MOCK_NET_DEVICE_H */

model/orbit.h

@@ -21,12 +21,27 @@
 
 #include "ns3/uinteger.h"
 
+/**
+ * \file
+ * \ingroup leo
+ * Declares Orbit
+ */
+
+/**
+ * \ingroup leo
+ * \brief Orbit
+ */
 class Orbit {
 public:
+  /// constructor
   Orbit (double a, double i, double p, double s) : alt (a), inc (i), planes (p), sats (s) {}
+  /// Altitude
   double alt;
+  /// Inclination
   double inc;
+  /// Number of planes
   uint16_t planes;
+  /// Number of satellites in plane
   uint16_t sats;
 };