[Positioning] Doxygen comments + fixes

- Add/update comments to be Doxygen compliant. Translate existing
  comments in English.
- Various fixes (more or less importants):
	- NULL pointer verification when adding an element to a vector of
	  pointers.
	- Add some missing accessors.
	- Add some more error handling with exceptions. Class Stock: correct
	  accessors (pure read accessors do not create a missing element any
		more, but throw an exception).
- Makefile: Add 'doc' target.
- Update TODO (some things noticed when reviewing the code for
  comments).

owlps-positioning/.gitignore

@@ -0,0 +1,2 @@
+doc
+csv/*.csv

owlps-positioning/Makefile

@@ -1,4 +1,7 @@
-.PHONY : all clean purge install uninstall style
+.PHONY : all obj doc clean purge install uninstall style
+
+DOXYGEN_DIR = doc
+DOXYFILE = Doxyfile
 
 # Répertoire d'installation
 PREFIX = /usr/local
@@ -6,10 +9,12 @@ INSTALL_DIR =  $(PREFIX)/bin
 
 # Commandes d'installation et de désinstallation
 RM = rm -fv
+RM_RECURSIVE = $(RM) -r
 CP = cp -v
 
 # Autres outils
 STYLE = astyle --style=gnu
+DOXYGEN = doxygen
 
 GXX = g++-4.4
 DEBUG = -g
@@ -56,11 +61,15 @@ obj: $(OBJ)
 
 $(TARGET): $(OBJ)
 
+doc:
+	@$(DOXYGEN) $(DOXYFILE)
+
 clean:
-	@rm -fv *~ *.o *.gch *.orig
+	@$(RM) *~ *.o *.gch *.orig
 
 purge: clean
-	@rm -f $(TARGET)
+	@$(RM) $(TARGET)
+	@$(RM_RECURSIVE) $(DOXYGEN_DIR)
 
 install: $(TARGET)
 	@$(CP) $(TARGET) $(INSTALL_DIR) && \

owlps-positioning/TODO

@@ -1,11 +1,11 @@
 
 - InputCSV
+   ° Lancer une exception si l'ouverture du fichier d'entrée échoue.
+   ° Expliquer ce que fait get_next_request().
    ° Différencier une requête normale d'une requête de calibration, en
    utilisant les champs de direction.
    ° Lire la direction en tant qu'entier plutôt que float ?
 
-- Commentaires doxygen
-
 - Tests unitaires
 
 - Affichage de debug
@@ -27,6 +27,15 @@
    ° Compositions : devraient être représentées par des attributs
    normaux.
 
+- Building
+   Dans le destructeur, vérifier qu'il faut bien supprimer les Area et
+   les Waypoint. Si oui, faut-il aussi les enlever des listes dans
+   Stock ? (Pour l'instant ils ne sont pas dans Stock.)
+
+- CalibrationMeasurement
+   Vérifier que l'operator<<() est utile (puisqu'il y a celui de
+   Measurement).
+
 - Request
    Constructeur par recopie, operator==(), etc.
 
@@ -39,6 +48,10 @@
 - Mobile
    Attributs Viterbi ? (Cf. l'ancien clientinfo.hh.)
 
+- Doxygen
+   Pourquoi une description détaillée placée dans un .cc ne s'affiche
+   pas pour operator<<() ?
+
 - C++ en action
    Espaces de noms ? 109
    Réserver l'espace mémoire des vector avec reserve(). 217

owlps-positioning/accesspoint.cc

@@ -5,7 +5,7 @@ using namespace std ;
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const AccessPoint& AccessPoint::operator=(const AccessPoint &ap)

owlps-positioning/accesspoint.hh

@@ -7,17 +7,16 @@
 #define AP_DEFAULT_CHANNEL 6
 #define AP_DEFAULT_ANTENNA_GAIN 5
 
+/// Represents a capture \link WifiDevice Wi-Fi device\endlink
 class AccessPoint: public WifiDevice
 {
 protected:
-  Point3D coordinates ;
+  Point3D coordinates ; ///< Coordinates of the AccessPoint
-  unsigned int frequency ; // Frequency (channel) in Hz
+  unsigned int frequency ; ///< Frequency (channel) in Hz
 
 public:
-  AccessPoint(const WifiDevice &wd,
+  /// \brief Constructs an AccessPoint by defining all of its
-              const Point3D &_coordinates,
+  /// attributes (or default constructor)
-              const unsigned int &_frequency = AP_DEFAULT_CHANNEL):
-    WifiDevice(wd), coordinates(_coordinates), frequency(_frequency) {}
   AccessPoint(const Point3D &_coordinates = Point3D(),
               const std::string &_ip_addr = "",
               const std::string &_mac_addr = "",
@@ -26,29 +25,53 @@ public:
               const unsigned int &_frequency = AP_DEFAULT_CHANNEL):
     WifiDevice(_ip_addr, _mac_addr, _antenna_gain, _trx_power),
     coordinates(_coordinates), frequency(_frequency) {}
+
+  /// Constructs an AccessPoint from a WifiDevice, a Point3D and a frequency
+  AccessPoint(const WifiDevice &wd,
+              const Point3D &_coordinates,
+              const unsigned int &_frequency = AP_DEFAULT_CHANNEL):
+    WifiDevice(wd), coordinates(_coordinates), frequency(_frequency) {}
+
+  /// Constructs an AccessPoint from a WifiDevice
   AccessPoint(const WifiDevice &wd):
     WifiDevice(wd), coordinates(Point3D()), frequency(0) {}
+
+  /// Copy constructor
   AccessPoint(const AccessPoint &ap):
     WifiDevice(ap), coordinates(ap.coordinates), frequency(ap.frequency) {}
 
-  ~AccessPoint() {}
+  ~AccessPoint(void) {} ///< Destructor (do nothing)
 
+  /** @name Read accessors */
+  //@{
+  /// #coordinates read accessor
   const Point3D& get_coordinates(void) const ;
+  /// #frequency read accessor
   unsigned int get_frequency(void) const ;
+  //@}
 
-  void set_coordinates(Point3D &_coordinates) ;
+  /** @name Write accessors */
-  void set_frequency(unsigned int &_frequency) ;
+  //@{
+  /// #coordinates write accessor
+  void set_coordinates(const Point3D &_coordinates) ;
+  /// #frequency write accessor
+  void set_frequency(const unsigned int _frequency) ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const AccessPoint& operator=(const AccessPoint &ap) ;
   bool operator==(const AccessPoint &ap) const ;
   bool operator!=(const AccessPoint &ap) const ;
+  //@}
 
+  /// Displays an AccessPoint
   friend std::ostream &operator<<(std::ostream &os, const AccessPoint &ap) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline const Point3D& AccessPoint::get_coordinates() const
@@ -64,23 +87,23 @@ inline unsigned int AccessPoint::get_frequency() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
-inline void AccessPoint::set_coordinates(Point3D &_coordinates)
+inline void AccessPoint::set_coordinates(const Point3D &_coordinates)
 {
   coordinates = _coordinates ;
 }
 
 
-inline void AccessPoint::set_frequency(unsigned int &_frequency)
+inline void AccessPoint::set_frequency(const unsigned int _frequency)
 {
   frequency = _frequency ;
 }
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool AccessPoint::operator!=(const AccessPoint &ap) const

owlps-positioning/area.cc

@@ -4,7 +4,8 @@
 using namespace std ;
 
 
-/*** Constructeurs ***/
+
+/* *** Constructors *** */
 
 
 Area::Area(const Building *_building, const string &_name,
@@ -82,9 +83,13 @@ Area::Area(const Area &a)
 
 
 
-/*** Opérations ***/
+/* *** Operations *** */
 
 
+/**
+ * @return \em true if \em p is into the Area.
+ * @return \em false if \em p is not into the Area.
+ */
 bool Area::contains_point(const Point3D &p) const
 {
   return
@@ -98,7 +103,7 @@ bool Area::contains_point(const Point3D &p) const
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 bool Area::operator==(const Area &a) const
@@ -115,6 +120,10 @@ bool Area::operator==(const Area &a) const
 
 
 
+/**
+ * Note: to avoid looping, the Building associated with the Area is
+ * not displayed.
+ */
 ostream &operator<<(ostream &os, const Area &a)
 {
   os << a.name << ';'

owlps-positioning/area.hh

@@ -8,49 +8,78 @@ class Building ;
 #include <string>
 #include <ostream>
 
+/// Represents an homogeneous area (typically a room) of a Building
 class Area
 {
 protected:
-  Building *building ;
+  Building *building ; ///< The Building in which the Area is
-  std::string name ;
+  std::string name ; ///< Name of the Area
-  Point3D p_min ;
+  Point3D p_min ; ///< First coordinate of the Area
-  Point3D p_max ;
+  Point3D p_max ; ///< Second coordinate of the Area
 
 public:
-  Area(const Building *_building, const std::string &_name = "Unnamed area",
+  /// \brief Constructs an Area from a Building, a name and two 3-float
+  /// defined points (or default constructor)
+  Area(const Building *_building = NULL,
+       const std::string &_name = "Unnamed area",
        const float &_x1 = 0, const float &_y1 = 0, const float &_z1 = 0,
        const float &_x2 = 0, const float &_y2 = 0, const float &_z2 = 0) ;
+  /// Copy constructor
   Area(const Area &a) ;
 
-  ~Area() {}
+  ~Area(void) {} ///< Destructor (do nothing)
 
-  Building* get_building(void) const ;
+  /** @name Read accessors */
-  const std::string& get_name(void) const ;
+  //@{
-  const Point3D& get_p_min(void) const ;
+  Building* get_building(void) const ; ///< #building read accessor
-  const Point3D& get_p_max(void) const ;
+  const std::string& get_name(void) const ; ///< #name read accessor
+  const Point3D& get_p_min(void) const ; ///< #p_min read accessor
+  const Point3D& get_p_max(void) const ; ///< #p_max read accessor
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// #building write accessor
   void set_building(const Building *_building) ;
+  /// #name write accessor
   void set_name(const std::string &_name) ;
+  /// Sets the X of #p_min
   void set_x_min(const float &v) ;
+  /// Sets the Y of #p_min
   void set_y_min(const float &v) ;
+  /// Sets the Z of #p_min
   void set_z_min(const float &v) ;
+  /// Sets the X of #p_max
   void set_x_max(const float &v) ;
+  /// Sets the Y of #p_max
   void set_y_max(const float &v) ;
+  /// Sets the Z of #p_max
   void set_z_max(const float &v) ;
+  /// #p_min write accessor
   void set_p_min(const Point3D &p) ;
+  /// #p_max write accessor
   void set_p_max(const Point3D &p) ;
+  //@}
 
+  /** @name Operations */
+  //@{
+  /// Checks if a Point3D is into the Area
   bool contains_point(const Point3D &p) const ;
+  //@}
 
+  /** @name Operators */
+  //@{
   bool operator==(const Area &a) const ;
   bool operator!=(const Area &a) const ;
+  //@}
 
+  /// Displays an Area
   friend std::ostream &operator<<(std::ostream &os, const Area &a) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline Building* Area::get_building() const
@@ -78,7 +107,7 @@ inline const Point3D& Area::get_p_max() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
 inline void Area::set_building(const Building *_building)
@@ -142,7 +171,7 @@ inline void Area::set_p_max(const Point3D &p)
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool Area::operator!=(const Area &a) const

owlps-positioning/building.cc

@@ -7,7 +7,7 @@ using namespace std ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
 Building::Building(const string &_name)
@@ -26,11 +26,10 @@ Building::Building(const Building &b)
 
 
 
-/*
+/**
- * Destructor
+ * Note: deletes (unallocates) all elements in #areas; deletes elements
- * Note: deletes (unallocates) all elements in areas; deletes elements in
+ * in #waypoints that belong only to this Building (waypoints that link
- *   waypoints that belong only to this Building (waypoints that link)
+ * several buildings are preserved).
- *   several buildings are preserved).
  */
 Building::~Building()
 {
@@ -52,7 +51,7 @@ Building::~Building()
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const Building& Building::operator=(const Building &b)

owlps-positioning/building.hh

@@ -8,37 +8,56 @@ class Waypoint ;
 #include <vector>
 #include <ostream>
 
+/// Represents a building, containing one or more Area
 class Building
 {
 protected:
-  std::string name ;
+  std::string name ; ///< Name of the Building
-  std::vector<Area*> areas ;
+  std::vector<Area*> areas ; ///< List of Area contained in the Building
-  std::vector<Waypoint*> waypoints ;
+  std::vector<Waypoint*> waypoints ; ///< List of Waypoint in the Building
 
 public :
+  /// Constructs a Building from its name (or default constructor)
   Building(const std::string &_name = "Unnamed building") ;
+  /// Copy constructor
   Building(const Building &b) ;
 
-  ~Building(void) ;
+  ~Building(void) ; ///< Destructor
 
+  /** @name Read accessors */
+  //@{
+  /// #name read accessor
   const std::string& get_name(void) const ;
+  /// #areas read accessor
   const std::vector<Area*>& get_areas(void) const ;
+  /// #waypoints read accessor
   const std::vector<Waypoint*>& get_waypoints(void) const ;
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// #name write accessor
   void set_name(const std::string &_name) ;
+  /// Adds an Area to the \link #areas list of areas\endlink
   void add_area(const Area *a) ;
+  /// Adds a Waypoint to the \link #waypoints list of waypoints\endlink
   void add_waypoint(const Waypoint *wp) ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const Building& operator=(const Building &p) ;
   bool operator==(const Building &p) const ;
   bool operator!=(const Building &p) const ;
+  //@}
 
+  /// Displays a Building
   friend std::ostream& operator<<(std::ostream &os, const Building &b) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline const std::string& Building::get_name() const
@@ -60,7 +79,7 @@ inline const std::vector<Waypoint*>& Building::get_waypoints() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
 inline void Building::set_name(const std::string &_name)
@@ -69,20 +88,30 @@ inline void Building::set_name(const std::string &_name)
 }
 
 
+/**
+ * @param a A pointer to the Area to add. If \em a is NULL, nothing
+ * will be added.
+ */
 inline void Building::add_area(const Area *a)
 {
-  areas.push_back((Area *) a) ;
+  if (a != NULL)
+    areas.push_back((Area *) a) ;
 }
 
 
+/**
+ * @param wp A pointer to the Waypoint to add. If \em wp is NULL,
+ * nothing will be added.
+ */
 inline void Building::add_waypoint(const Waypoint *wp)
 {
-  waypoints.push_back((Waypoint *) wp) ;
+  if (wp != NULL)
+    waypoints.push_back((Waypoint *) wp) ;
 }
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool Building::operator!=(const Building &b) const

owlps-positioning/calibrationmeasurement.cc

@@ -2,7 +2,7 @@
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const CalibrationMeasurement&
@@ -30,6 +30,12 @@ bool CalibrationMeasurement::operator==(const CalibrationMeasurement &cm)
 
 
 
+/**
+ * Because a ReferencePoint displays its list of CalibrationMeasurement,
+ * the ReferencePoint associated with a CalibrationMeasurement is not
+ * displayed. Therefore, this is a simple mapping to
+ * operator<<(std::ostream&, const Measurement&)
+ */
 std::ostream &operator<<(std::ostream &os, const CalibrationMeasurement &cm)
 {
   os

owlps-positioning/calibrationmeasurement.hh

@@ -5,38 +5,56 @@ class ReferencePoint ;
 
 #include "measurement.hh"
 
+/// Represents a Measurement that constructed from calibration Request
 class CalibrationMeasurement: public Measurement
 {
 protected:
+  /// The reference point the mobile calibrates
   ReferencePoint *reference_point ;
 
 public:
+  /// \brief Constructs a CalibrationMeasurement from an AccessPoint, a
+  /// list of signal strengths and a ReferencePoint (or default constructor)
   CalibrationMeasurement(const AccessPoint *_ap = NULL,
                          const std::vector<int> &_ss_list = std::vector<int>(),
                          ReferencePoint *_reference_point = NULL):
     Measurement(_ap, _ss_list), reference_point(_reference_point) {}
+  /// Copy constructor
   CalibrationMeasurement(const CalibrationMeasurement &cm):
     Measurement(cm), reference_point(cm.reference_point) {}
+  /// Constructs a CalibrationMeasurement from a Measurement
   CalibrationMeasurement(const Measurement &m):
     Measurement(m), reference_point(NULL) {}
 
-  ~CalibrationMeasurement() {}
+  ~CalibrationMeasurement(void) {} ///< Destructor (do nothing)
 
+  /** @name Read accessors */
+  //@{
+  /// #reference_point read accessor
   ReferencePoint* get_reference_point(void) const ;
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// #reference_point write accessor
   void set_reference_point(const ReferencePoint *_rp) ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const CalibrationMeasurement& operator=(const CalibrationMeasurement &cm) ;
   bool operator==(const CalibrationMeasurement &cm) ;
   bool operator!=(const CalibrationMeasurement &cm) ;
+  //@}
 
+  /// Displays a CalibrationMeasurement
   friend std::ostream &operator<<(std::ostream &os,
                                   const CalibrationMeasurement &cm) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline ReferencePoint* CalibrationMeasurement::get_reference_point(void) const
@@ -46,7 +64,7 @@ inline ReferencePoint* CalibrationMeasurement::get_reference_point(void) const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
 inline void CalibrationMeasurement::set_reference_point(
@@ -57,7 +75,7 @@ inline void CalibrationMeasurement::set_reference_point(
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool CalibrationMeasurement::operator!=(const CalibrationMeasurement &cm)

owlps-positioning/csv/.gitignore

@@ -1 +0,0 @@
-*.csv

owlps-positioning/inputcsv.cc

@@ -17,9 +17,14 @@ using namespace boost ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
+/**
+ * Prepares the InputCSV to read a CSV file.
+ * @param filename The name of the file to open.
+ * @throw FIXME if the file cannot be opened.
+ */
 InputCSV::InputCSV(const string &filename)
 {
   input_file_name = filename ;
@@ -33,9 +38,12 @@ InputCSV::InputCSV(const string &filename)
 
 
 
-/*** Opérations ***/
+/* *** Operations *** */
 
 
+/**
+ * FIXME Detailed description comming soon…
+ */
 const Request& InputCSV::get_next_request()
 {
   if (! input_file)

owlps-positioning/inputcsv.hh

@@ -6,27 +6,47 @@
 #include <string>
 #include <fstream>
 
+/// Reads requests (Request) from a CSV file
 class InputCSV: public InputMedium
 {
 protected:
+  /// Name of the input CSV file
   std::string input_file_name ;
+  /// Stream corresponding to the input CSV file
   std::ifstream input_file ;
 
 public:
-  InputCSV(const std::string &filename = "") ;
+  /// Constructs an InputCSV from a CSV input file name
+  InputCSV(const std::string &filename) ;
 
+  /** @name Read accessors */
+  //@{
+  /// Checks if the end of the CSV file has been reached
   bool eof(void) const ;
+  //@}
 
+  /** @name Operations */
+  //@{
+  /// Reads the next request
   const Request& get_next_request(void) ;
+  //@}
 
+  /** @name Operators */
+  //@{
+  /// Cast to bool operator
   operator bool(void) const ;
+  //@}
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
+/**
+ * @return \em true if the end of file is reached.
+ * @return \em false if there is something more to read.
+ */
 inline bool InputCSV::eof() const
 {
   return input_file.eof() ;
@@ -34,9 +54,13 @@ inline bool InputCSV::eof() const
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
+/**
+ * @return The bool value of #input_file.
+ * @sa std::ifstream
+ */
 inline InputCSV::operator bool() const
 {
   return input_file ;

owlps-positioning/inputmedium.hh

@@ -3,34 +3,62 @@
 
 #include "request.hh"
 
+/// Super class of all input media
+/**
+ * Provide interface for input media, i.e. to read Request sent by a
+ * Mobile.
+ */
 class InputMedium
 {
 protected:
+  /// The Request just read
   Request current_request ;
+  /// Number of the current line proceeded
   unsigned long current_line ;
 
 public:
-  InputMedium() ;
+  /// Default constructor
+  InputMedium(void) ;
 
+  virtual ~InputMedium(void) {} ///< Destructor (do nothing)
+
+  /** @name Read accessors */
+  //@{
+
+  /// #current_request read accessor
   const Request& get_current_request(void) const ;
+
+  /// #current_line read accessor
   unsigned int get_current_line(void) const ;
 
-  /*
+  /// Checks if the last request has been reached
-   * Reads the next request and returns it, increments current_line
+  /**
-   * Returns an empty Request in case of error or EOF (note that
+   * @return \em true if the last request has been reached.
-   * when casted in bool, an empty Request is false).
+   * @return \em false if there is something more to read.
+   */
+  virtual bool eof(void) const = 0 ;
+
+  //@} // End Read accessors
+
+  /** @name Operations */
+  //@{
+
+  /// Reads the next request
+  /**
+   * Reads a Request, increments current_line, updates #current_request
+   * and returns it.
+   * @return The Request read, or an empty Request in case of error or
+   * EOF (note that when casted in bool, an empty Request is false, see
+   * Request::operator bool()).
    */
   virtual const Request& get_next_request(void) = 0 ;
 
-  /*
+  //@} // End Operations
-   * Returns true if the last request has been reached
-   */
-  virtual bool eof(void) const = 0 ;
 } ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
 inline InputMedium::InputMedium()
@@ -40,7 +68,7 @@ inline InputMedium::InputMedium()
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline const Request& InputMedium::get_current_request() const

owlps-positioning/measurement.cc

@@ -5,7 +5,7 @@ using namespace std ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
 Measurement::Measurement(const AccessPoint *_ap,
@@ -26,9 +26,9 @@ Measurement::Measurement(const Measurement &m)
 }
 
 
-/*
+
- * Destructor
+/**
- * ap and mobile are not deleted.
+ * Note that values pointed by #ap are not deleted.
  */
 Measurement::~Measurement()
 {
@@ -37,7 +37,7 @@ Measurement::~Measurement()
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
 void Measurement::update_average_ss()
@@ -55,6 +55,9 @@ void Measurement::update_average_ss()
 }
 
 
+/**
+ * #average_ss is updated to include the new value.
+ */
 void Measurement::add_ss(const int &ss)
 {
   float ss_mwatts =
@@ -65,6 +68,10 @@ void Measurement::add_ss(const int &ss)
 }
 
 
+/**
+ * update_average_ss() is automatically called to recalculate
+ * #average_ss.
+ */
 void Measurement::set_ss_list(const std::vector<int> &_ss_list)
 {
   ss_list = _ss_list ;
@@ -72,9 +79,10 @@ void Measurement::set_ss_list(const std::vector<int> &_ss_list)
 }
 
 
-/*
+/**
- * Reinitialises the Measurement
+ * - #ap is not deleted, only initialised to NULL.
- * ap and mobile are not deleted, only initialised at NULL.
+ * - #ss_list is cleared.
+ * - #average_ss is initialised to 0.
  */
 void Measurement::clear()
 {
@@ -85,7 +93,7 @@ void Measurement::clear()
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const Measurement& Measurement::operator=(const Measurement &m)

owlps-positioning/measurement.hh

@@ -7,43 +7,68 @@
 #include <ostream>
 #include <cmath>
 
+/// Represents a list of signal strengths captured by one AccessPoint
 class Measurement
 {
 protected:
+  /// The AccessPoint that performed the measurement
   AccessPoint *ap ;
-  float average_ss ;
+  /// List of signal strengths captured
   std::vector<int> ss_list ;
+  /// Average of all signal strength captured
+  float average_ss ;
 
+  /// Recalculates #average_ss from #ss_list
   void update_average_ss(void) ;
 
 public:
+  /// \brief Constructs a Measurement from an AccessPoint and a list
+  /// of signal strengths (or default constructor)
   Measurement(const AccessPoint *_ap = NULL,
               const std::vector<int> &_ss_list = std::vector<int>()) ;
+  /// Copy constructor
   Measurement(const Measurement &m) ;
 
-  ~Measurement() ;
+  ~Measurement(void) ; ///< Destructor
 
+  /** @name Read accessors */
+  //@{
+  /// #ap read accessor
   AccessPoint* get_ap() const ;
+  /// #ss_list read accessor
   const std::vector<int>& get_ss_list() const ;
+  /// #average_ss read accessor
   float get_average_ss() const ;
   //float get_ss_square_distance(const float &ss) const ;
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// #ap write accessor
   void set_ap(const AccessPoint *_ap) ;
+  /// Adds a signal strength to #ss_list
   void add_ss(const int &ss) ;
+  /// #ss_list write accessor
   void set_ss_list(const std::vector<int> &_ss_list) ;
+  /// Reinitialises the Measurement
   void clear(void) ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const Measurement& operator=(const Measurement &m) ;
   bool operator==(const Measurement &m) const ;
   bool operator!=(const Measurement &m) const ;
-  operator bool(void) const ;
+  operator bool(void) const ; ///< Cast to bool operator
+  //@}
 
+  /// Displays a Measurement
   friend std::ostream &operator<<(std::ostream &os, const Measurement &m) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline AccessPoint* Measurement::get_ap() const
@@ -71,7 +96,7 @@ inline float Measurement::get_average_ss() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** write accessors *** */
 
 
 inline void Measurement::set_ap(const AccessPoint *_ap)
@@ -81,7 +106,7 @@ inline void Measurement::set_ap(const AccessPoint *_ap)
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool Measurement::operator!=(const Measurement &m) const
@@ -90,9 +115,9 @@ inline bool Measurement::operator!=(const Measurement &m) const
 }
 
 
-/*
+/**
- * Returns false if the Measurement is empty, or true if at least one
+ * @return \em false if the Measurement is empty.
- * attribute is initialised.
+ * @return \em true if at least one attribute is initialised.
  */
 inline Measurement::operator bool() const
 {

owlps-positioning/mobile.cc

@@ -2,7 +2,7 @@
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const Mobile& Mobile::operator=(const Mobile &m)

owlps-positioning/mobile.hh

@@ -7,31 +7,41 @@
 
 #define MOBILE_DEFAULT_ANTENNA_GAIN 2
 
+/// \brief Represents a mobile \link WifiDevice Wi-Fi device\endlink
+/// that can be localised
 class Mobile: public WifiDevice
 {
 public:
+  /// Constructs a Mobile by defining all (or none) of its attributes
+  /** This constructor is just a mapping of WifiDevice(). */
   Mobile(const std::string &_ip_addr = "",
          const std::string &_mac_addr = "",
          const float &_antenna_gain = MOBILE_DEFAULT_ANTENNA_GAIN,
          const float &_trx_power = WIFIDEVICE_DEFAULT_TRX_POWER):
     WifiDevice(_ip_addr, _mac_addr, _antenna_gain, _trx_power) {}
+  /// Constructs a Mobile from a WifiDevice
   Mobile(const WifiDevice &wd):
     WifiDevice(wd) {}
+  /// Copy constructor
   Mobile(const Mobile &m):
     WifiDevice(m) {}
 
-  ~Mobile() {}
+  ~Mobile(void) {} ///< Destructor (do nothing)
 
+  /** @name Operators */
+  //@{
   const Mobile& operator=(const Mobile &m) ;
   bool operator==(const Mobile &m) const ;
   bool operator!=(const Mobile &m) const ;
+  //@}
 
+  /// Displays a Mobile
   friend std::ostream &operator<<(std::ostream &os, const Mobile &m) ;
 } ;
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool Mobile::operator!=(const Mobile &m) const

owlps-positioning/point3d.cc

@@ -2,7 +2,7 @@
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
 Point3D::Point3D(const float &_x, const float &_y, const float &_z)
@@ -30,11 +30,12 @@ Point3D::Point3D(const float c[3])
 
 
 
-/*** Calcul de distances ***/
+/* *** Distance operations *** */
 
 
-/*
+/**
- * Distance carrée à un point (Point3D)
+ * The distance is not square rooted after the computation, in order
+ * to optimise comparisons.
  */
 float Point3D::square_distance(const Point3D &p) const
 {
@@ -45,8 +46,9 @@ float Point3D::square_distance(const Point3D &p) const
 }
 
 
-/*
+/**
- * Distance carrée à un point décrit par ses coordonnées
+ * The distance is not square rooted after the computation, in order
+ * to optimise comparisons.
  */
 float Point3D::square_distance(const float &_x,
                                const float &_y,
@@ -60,7 +62,7 @@ float Point3D::square_distance(const float &_x,
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const Point3D& Point3D::operator=(const Point3D &p)

owlps-positioning/point3d.hh

@@ -4,38 +4,57 @@
 #include <ostream>
 #include <cmath>
 
+/// Represents a point of the 3-D space
 class Point3D
 {
 protected:
-  float x ;
+  float x ; ///< X horizontal coordinate (abscissa)
-  float y ;
+  float y ; ///< Y horizontal coordinate (ordinate)
-  float z ;
+  float z ; ///< Vertical coordinate
 
 public:
+  /// 3 float constructor or default constructor
   Point3D(const float &_x = 0, const float &_y = 0, const float &_z = 0) ;
+  /// Copy constructor
   Point3D(const Point3D &p) ;
+  /// 3-float array constructor
   Point3D(const float c[3]) ;
 
-  virtual ~Point3D(void) {}
+  virtual ~Point3D(void) {} ///< Destructor (do nothing)
 
-  float get_x(void) const ;
+  /** @name Read accessors */
-  float get_y(void) const ;
+  //@{
-  float get_z(void) const ;
+  float get_x(void) const ; ///< #x read accessor
+  float get_y(void) const ; ///< #y read accessor
+  float get_z(void) const ; ///< #z read accessor
+  //@}
 
-  void set_x(const float &_x) ;
+  /** @name Write accessors */
-  void set_y(const float &_y) ;
+  //@{
-  void set_z(const float &_z) ;
+  void set_x(const float &_x) ; ///< #x write accessor
-  void set_coordinates(const Point3D &p) ;
+  void set_y(const float &_y) ; ///< #y write accessor
+  void set_z(const float &_z) ; ///< #z write accessor
+  void set_coordinates(const Point3D &p) ; ///< Sets all coordinates
+  //@}
 
+  /** @name Distance operations */
+  //@{
+  /// Square euclidean distance to a Point3D
   float square_distance(const Point3D &p) const ;
+  /// Euclidean distance to a Point3D
   float distance(const Point3D &p) const ;
+  /// Square euclidean distance to a 3-float defined point
   float square_distance(const float &mx,
                         const float &my,
                         const float &mz) const ;
+  /// Euclidean distance to a 3-float defined point
   float distance(const float &mx,
                  const float &my,
                  const float &mz) const ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const Point3D& operator=(const Point3D &p) ;
   bool operator==(const Point3D &p) const ;
   bool operator!=(const Point3D &p) const ;
@@ -43,13 +62,15 @@ public:
   bool operator>(const Point3D &p) const ;
   bool operator<=(const Point3D &p) const ;
   bool operator>=(const Point3D &p) const ;
+  //@}
 
+  /// Displays a Point3D
   friend std::ostream& operator<<(std::ostream &os, const Point3D &p) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline float Point3D::get_x() const
@@ -71,7 +92,7 @@ inline float Point3D::get_z() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
 inline void Point3D::set_x(const float &_x)
@@ -92,8 +113,8 @@ inline void Point3D::set_z(const float &_z)
 }
 
 
-/*
+/**
- * Updates x, y, z by passing a Point3D
+ * Updates x, y, z by passing a Point3D.
  * This is useful for derivated classes, and different than a direct
  * call to operator=().
  */
@@ -104,13 +125,12 @@ inline void Point3D::set_coordinates(const Point3D &p)
 
 
 
-/*** Calcul de distances ***/
+/* *** Distance operations *** */
 
 
-/*
+/**
- * Distance à un point (Point3D)
+ * Note: to compare distances, use preferably square_distance(),
- * Note : pour comparer deux distances, utiliser de préférence
+ * which is more efficient.
- *        square_distance, qui fait économiser une racine carrée.
  */
 inline float Point3D::distance(const Point3D &p) const
 {
@@ -118,10 +138,9 @@ inline float Point3D::distance(const Point3D &p) const
 }
 
 
-/*
+/**
- * Distance à un point décrit par ses coordonnées
+ * Note: to compare distances, use preferably square_distance(),
- * Note : pour comparer deux distances, utiliser de préférence
+ * which is more efficient.
- *        square_distance, qui fait économiser une racine carrée.
  */
 inline float Point3D::distance(const float &_x,
                                const float &_y,
@@ -132,7 +151,7 @@ inline float Point3D::distance(const float &_x,
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool Point3D::operator!=(const Point3D &p) const

owlps-positioning/posutil.cc

@@ -2,9 +2,11 @@
 
 
 
-/*
+/**
- * Returns the frequency in Hz corresponding to the 802.11 channel "channel"
+ * @param channel A IEEE 802.11 channel.
- * or 0 if the channel is wrong.
+ * @return The frequency in Hz or 0 if the channel is wrong.
+ * Note that if \em channel is a frequency in Hz, this function will
+ * consider it as a wrong value and return 0.
  */
 unsigned int PosUtil::channel_to_frequency(const int &channel)
 {

owlps-positioning/posutil.hh

@@ -20,17 +20,27 @@
 #define CHANNEL_13 2472
 #define CHANNEL_14 2477
 
+/// Utilitary class
 class PosUtil
 {
 public:
-  /* Wi-Fi */
+  /** @name Wi-Fi */
+  //@{
+  /// Converts a Wi-Fi channel to the corresponding frequency in Hz
   static unsigned int channel_to_frequency(const int &channel) ;
+  //@}
 
-  /* Time & Dates */
+  /** @name Time & Dates */
+  //@{
+  /// Converts a struct timespec into a value in milliseconds
   static uint64_t timespec_to_ms(const struct timespec &d) ;
+  /// Converts a time value in milliseconds into a struct timespec
   static struct timespec ms_to_timespec(const uint64_t &tms) ;
+  /// Converts a struct timespec into a value in nanoseconds
   static uint64_t timespec_to_ns(const struct timespec &d) ;
+  /// Converts a time value in nanoseconds into a struct timespec
   static struct timespec ns_to_timespec(const uint64_t &tns) ;
+  //@}
 } ;
 
 #endif // _OWLPS_POSITIONING_POSUTIL_HH_

owlps-positioning/referencepoint.cc

@@ -5,9 +5,13 @@ using namespace std ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
+/**
+ * Clears #measurements, but does not deallocate the values pointed by
+ * the elements into it.
+ */
 ReferencePoint::~ReferencePoint()
 {
   measurements.clear() ;
@@ -122,7 +126,7 @@ ReferencePoint::~ReferencePoint()
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const ReferencePoint& ReferencePoint::operator=(const ReferencePoint &rp)

owlps-positioning/referencepoint.hh

@@ -8,36 +8,55 @@ class CalibrationMeasurement ;
 #include <vector>
 #include <ostream>
 
+/// Represents a reference point in 3-D space
 class ReferencePoint: public Point3D
 {
 protected:
+  /// List of CalibrationMeasurement associated with the ReferencePoint
+  /** Note that \em measurements is a \em pointer list: only pointers
+      are stored, not values. */
   std::vector<CalibrationMeasurement*> measurements ;
 
 public:
+  /// 3-float constructor or default constructor
   ReferencePoint(const float &_x = 0, const float &_y = 0, const float &_z = 0):
     Point3D(_x, _y, _z) {}
+  /// Constructs a ReferencePoint from a Point3D
   ReferencePoint(const Point3D &p): Point3D(p) {}
+  /// Copy constructor
   ReferencePoint(const ReferencePoint &rp):
     Point3D(rp), measurements(rp.measurements) {}
 
-  ~ReferencePoint() ;
+  ~ReferencePoint(void) ; ///< Destructor
 
+  /** @name Read accessors */
+  //@{
+  /// #measurements read accessor
   const std::vector<CalibrationMeasurement*>& get_measurements(void) const ;
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// Adds a Measurement to the \link #measurements measurement list\endlink
   void add_measurement(const CalibrationMeasurement *cm) ;
   //  float get_ss_square_distance(const vector<CalibrationMeasurement> &m) const ;
   //  bool get_power_for_ap(const string &ap_mac, float *p) const ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const ReferencePoint& operator=(const ReferencePoint &rp) ;
   bool operator==(const ReferencePoint &rp) const ;
   bool operator!=(const ReferencePoint &rp) const ;
+  //@}
 
+  /// Displays a ReferencePoint
   friend std::ostream &operator<<(std::ostream &os, const ReferencePoint &rp) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline const
@@ -48,17 +67,25 @@ std::vector<CalibrationMeasurement*>& ReferencePoint::get_measurements() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
+/**
+ * @param cm A pointer to the CalibrationMeasurement to add. If it is
+ * NULL, nothing will be done.
+ * The memory pointed by this pointer must not be deallocated before
+ * the ReferencePoint destruction (do \em not pass a pointer to a local
+ * variable!).
+ */
 inline void ReferencePoint::add_measurement(const CalibrationMeasurement *cm)
 {
-  measurements.push_back((CalibrationMeasurement *) cm) ;
+  if (cm != NULL)
+    measurements.push_back((CalibrationMeasurement *) cm) ;
 }
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool ReferencePoint::operator!=(const ReferencePoint &rp) const

owlps-positioning/request.cc

@@ -6,7 +6,7 @@ using std::tr1::unordered_map ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
 Request::Request(const unordered_map<string, Measurement> &_measurements)
@@ -37,9 +37,24 @@ Request::Request(const Mobile *_mobile, const struct timespec &_timestamp,
 
 
 
-/*** Accesseurs écriture ***/
+/**
+ * Note that the value pointed by #mobile is not deleted.
+ */
+Request::~Request()
+{
+  measurements.clear() ;
+}
 
 
+
+/* *** Write accessors *** */
+
+
+/**
+ * - #mobile is NULLified, but the value it pointed to is not deleted.
+ * - The fields of #timestamp are initialised to 0.
+ * - #measurements is cleared.
+ */
 void Request::clear()
 {
   mobile = NULL ;
@@ -50,7 +65,7 @@ void Request::clear()
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 ostream &operator<<(ostream &os, const Request &r)

owlps-positioning/request.hh

@@ -9,39 +9,67 @@ class Mobile ;
 #include <unordered_map>
 #include <ostream>
 
+/// Represents a request sent by a Mobile
 class Request
 {
 protected:
+  /// The mobile that sent the request
   Mobile *mobile ;
+  /// Local date of the request on the mobile
   struct timespec timestamp ;
+  /// List of Measurement of the request
+  /** Note that this is not a pointer list, values are actually stored. */
   std::tr1::unordered_map<std::string, Measurement> measurements ;
 
 public:
+  /// Constructs a Request from a list of Measurement (or default constructor)
   Request(const std::tr1::unordered_map<std::string, Measurement> &_measurements
           = std::tr1::unordered_map<std::string, Measurement>()) ;
+  /// Constructs a Request from a timestamp and (possibly) a Measurement list
   Request(const struct timespec &_timestamp,
           const std::tr1::unordered_map<std::string, Measurement> &_measurements
           = std::tr1::unordered_map<std::string, Measurement>()) ;
+  /// \brief Constructs a request from a mobile and a timestamp and (possibly)
+  /// a Measurement list
   Request(const Mobile *_mobile, const struct timespec &_timestamp,
           const std::tr1::unordered_map<std::string, Measurement> &_measurements
           = std::tr1::unordered_map<std::string, Measurement>()) ;
 
-  Mobile* get_mobile(void) const ;
+  ~Request(void) ; ///< Destructor
 
+  /** @name Read accessors */
+  //@{
+  /// #mobile read accessor
+  Mobile* get_mobile(void) const ;
+  /// #timestamp read accessor
+  const struct timespec& get_timestamp(void) const ;
+  //@}
+
+  /** @name Write accessors */
+  //@{
+  /// #mobile write accessor
   void set_mobile(const Mobile *_mobile) ;
+  /// #timestamp write accessor
   void set_timestamp(const struct timespec &_timestamp) ;
+  /// #measurements write accessor
   void set_measurements(const std::tr1::unordered_map
                         <std::string, Measurement> &_measurements) ;
+  /// Reinitialises all attributes
   void clear(void) ;
+  //@}
 
-  operator bool(void) const ;
+  /** @name Operators */
+  //@{
+  operator bool(void) const ; ///< Cast to bool operator
+  //@}
 
+  /// Displays a Request
   friend std::ostream &operator<<(std::ostream &os, const Request &r) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline Mobile* Request::get_mobile() const
@@ -50,8 +78,14 @@ inline Mobile* Request::get_mobile() const
 }
 
 
+inline const struct timespec& Request::get_timestamp() const
+{
+  return timestamp ;
+}
 
-/*** Accesseurs écriture ***/
+
+
+/* *** Write accessors *** */
 
 
 inline void Request::set_mobile(const Mobile *_mobile)
@@ -74,12 +108,12 @@ inline void Request::set_measurements(const std::tr1::unordered_map
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
-/*
+/**
- * Returns false if the Request is empty, or true if at least one
+ * @return \em false if the Request is empty.
- * attribute is initialised.
+ * @return \em true if at least one attribute is initialised.
  */
 inline Request::operator bool() const
 {

owlps-positioning/stock.cc

@@ -1,12 +1,52 @@
 #include "stock.hh"
 
+#include <stdexcept>
+
 using namespace std ;
 using std::tr1::unordered_map ;
 
 
 
+/* *** Attribute definition *** */
+
 unordered_map<string, Mobile> Stock::mobiles =
   unordered_map<string, Mobile>() ;
 
 unordered_map<string, AccessPoint> Stock::aps =
   unordered_map<string, AccessPoint>() ;
+
+
+
+/* *** Read accessors *** */
+
+
+/**
+ * @param mac The MAC address of the Mobile to search for.
+ * It must be a valid MAC address, as no check is performed.
+ * @return A const reference to the Mobile.
+ * @throw std::out_of_range is thrown if the Mobile corresponding
+ * to \em mac does not exist.
+ */
+const Mobile& Stock::get_mobile(const string &mac)
+{
+  unordered_map<string, Mobile>::iterator i = mobiles.find(mac) ;
+  if (i != mobiles.end())
+    return i->second ;
+  throw out_of_range("No Mobile with MAC address « " + mac + " »!") ;
+}
+
+
+/**
+ * @param mac The MAC address of the AccessPoint to search for.
+ * It must be a valid MAC address, as no check is performed.
+ * @return A const reference to the AccessPoint.
+ * @throw std::out_of_range is thrown if the AccessPoint corresponding
+ * to \em mac does not exist.
+ */
+const AccessPoint& Stock::get_ap(const string &mac)
+{
+  unordered_map<string, AccessPoint>::iterator i = aps.find(mac) ;
+  if (i != aps.end())
+    return i->second ;
+  throw out_of_range("No AccessPoint with MAC address « " + mac + " »!") ;
+}

owlps-positioning/stock.hh

@@ -6,42 +6,52 @@
 
 #include <unordered_map>
 
+/// Storage class
 class Stock
 {
 private:
+  /// List of known Mobile
   static std::tr1::unordered_map<std::string, Mobile> mobiles ;
+
+  /// List of known AccessPoint
   static std::tr1::unordered_map<std::string, AccessPoint> aps ;
 
 public:
+  /// Read the Mobile corresponding to a given MAC address
   static const Mobile& get_mobile(const std::string &mac) ;
+  /// Get a reference to the Mobile corresponding to a given MAC address
   static Mobile& getw_mobile(const std::string &mac) ;
+
+  /// Read the AccessPoint corresponding to a given MAC address
   static const AccessPoint& get_ap(const std::string &mac) ;
+  /// Get a reference to the AccessPoint corresponding to a given MAC address
   static AccessPoint& getw_ap(const std::string &mac) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
-
-
-inline const Mobile& Stock::get_mobile(const std::string &mac)
-{
-  return mobiles[mac] ;
-}
 
 
+/**
+ * If the Mobile corresponding to \em mac does not exist, it is created.
+ * @param mac The MAC address of the Mobile to search for. It must be a
+ * valid MAC address, as no check is performed.
+ * @return A modifiable reference to the Mobile.
+ */
 inline Mobile& Stock::getw_mobile(const std::string &mac)
 {
   return mobiles[mac] ;
 }
 
 
-inline const AccessPoint& Stock::get_ap(const std::string &mac)
+/**
-{
+ * If the AccessPoint corresponding to \em mac does not exist, it is
-  return aps[mac] ;
+ * created.
-}
+ * @param mac The MAC address of the AccessPoint to search for.
-
+ * It must be a valid MAC address, as no check is performed.
-
+ * @return A modifiable reference to the AccessPoint.
+ */
 inline AccessPoint& Stock::getw_ap(const std::string &mac)
 {
   return aps[mac] ;

owlps-positioning/waypoint.cc

@@ -5,23 +5,41 @@ using namespace std ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
+/**
+ * @param _b A pointer to the (first) Building to add to #buildings.
+ * If it is NULL, #buildings will remain empty.
+ * @param p Coordinates of the Waypoint.
+ */
 Waypoint::Waypoint(const Building *_b, const Point3D &p): Point3D(p)
 {
-  buildings.push_back((Building *) _b) ;
+  if (_b != NULL)
+    buildings.push_back((Building *) _b) ;
 }
 
 
+/**
+ * @param _b A pointer to the (first) Building to add to #buildings.
+ * If it is NULL, #buildings will remain empty.
+ * @param _x X coordinate.
+ * @param _y Y coordinate.
+ * @param _z Z coordinate.
+ */
 Waypoint::Waypoint(const Building *_b,
                    const float &_x, const float &_y, const float &_z
                   ): Point3D(_x, _y, _z)
 {
-  buildings.push_back((Building *) _b) ;
+  if (_b != NULL)
+    buildings.push_back((Building *) _b) ;
 }
 
 
+/**
+ * Clears #buildings, but does not deallocate the values pointed by
+ * the elements into it.
+ */
 Waypoint::~Waypoint()
 {
   buildings.clear() ;
@@ -29,7 +47,7 @@ Waypoint::~Waypoint()
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const Waypoint& Waypoint::operator=(const Waypoint &wp)

owlps-positioning/waypoint.hh

@@ -9,37 +9,70 @@ class Building ;
 #include <vector>
 #include <stdexcept>
 
+/// Represents a junction point between several rooms (i.e. Area)
+/**
+ * A Waypoint is defined by its coordinates and linked to the buildings
+ * it belongs to. You \em should always construct a Waypoint with at least
+ * one associated Building, but you \em can not do so, for instance in an
+ * automatic construction (container…).
+ */
 class Waypoint: public Point3D
 {
 protected:
+  /// List of Building associated with the Waypoint
+  /** Note that \em buildings is a \em pointer list: only pointers
+      are stored, not values. */
   std::vector<Building*> buildings ;
 
 public:
+  /// Constructs a Waypoint from a Building pointer and a Point3D
   Waypoint(const Building *_b, const Point3D &p) ;
-  Waypoint(const Building *_b, const float &_x = 0, const float &_y = 0,
+  /// \brief Constructs a Waypoint from a Building pointer and a
-           const float &_z = 0) ;
+  /// 3-float defined point (or default constructor)
+  Waypoint(const Building *_b = NULL, const float &_x = 0,
+           const float &_y = 0, const float &_z = 0) ;
+  /// Constructs a Waypoint from a Point3D
   Waypoint(const Point3D &p): Point3D(p) {}
+  /// Copy constructor
   Waypoint(const Waypoint &wp): Point3D(wp), buildings(wp.buildings) {}
 
-  ~Waypoint(void) ;
+  ~Waypoint(void) ; ///< Destructor
 
+  /** @name Read accessors */
+  //@{
+  /// #buildings's first element read accessor
   Building* get_1st_building(void) const ;
+  /// #buildings read accessor
   const std::vector<Building*>& get_buildings(void) const ;
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// Adds a Building to the \link #buildings building list\endlink
   void add_building(const Building *_b) ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const Waypoint& operator=(const Waypoint &wp) ;
   bool operator==(const Waypoint &wp) const ;
   bool operator!=(const Waypoint &wp) const ;
+  //@}
 
+  /// Displays a Waypoint
   friend std::ostream& operator<<(std::ostream &os, const Waypoint &wp) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
+/**
+ * @return A pointer to the first Building associated with the Waypoint
+ * (i.e. the first element of #buildings). If #buildings is empty, NULL
+ * is returned.
+ */
 inline Building* Waypoint::get_1st_building() const
 {
   try
@@ -60,17 +93,25 @@ inline const std::vector<Building*>& Waypoint::get_buildings() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
+/**
+ * @param _b A pointer to the Building to add. If it is
+ * NULL, nothing will be done.
+ * The memory pointed by this pointer must not be deallocated before
+ * the Waypoint destruction (do \em not pass a pointer to a local
+ * variable!).
+ */
 inline void Waypoint::add_building(const Building *_b)
 {
-  buildings.push_back((Building *) _b) ;
+  if (_b != NULL)
+    buildings.push_back((Building *) _b) ;
 }
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool Waypoint::operator!=(const Waypoint &wp) const

owlps-positioning/wifidevice.cc

@@ -4,7 +4,7 @@ using namespace std ;
 
 
 
-/*** Constructeurs ***/
+/* *** Constructors *** */
 
 
 WifiDevice::WifiDevice(const string &_ip_addr,
@@ -29,7 +29,7 @@ WifiDevice::WifiDevice(const WifiDevice &wd)
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 const WifiDevice& WifiDevice::operator=(const WifiDevice &wd)

owlps-positioning/wifidevice.hh

@@ -9,43 +9,68 @@
 #define WIFIDEVICE_DEFAULT_ANTENNA_GAIN 2
 #define WIFIDEVICE_DEFAULT_TRX_POWER 20 // 20 dBm = 100 mW
 
+/// Represents a Wi-Fi enabled device
+/**
+ * This class is virtual, you have to derive it to create new types of
+ * Wi-Fi devices.
+ */
 class WifiDevice
 {
 protected:
-  std::string ip_addr ;
+  std::string ip_addr ; ///< IP address
-  std::string mac_addr ;
+  std::string mac_addr ; ///< MAC address
-  float antenna_gain ; // Antenna gain in dBi
+  float antenna_gain ; ///< Antenna gain in dBi
-  float trx_power ; // Transmit power in dBm
+  float trx_power ; ///< Transmit power in dBm
 
 public:
+  /// Constructs a WifiDevice by defining all (or none) of its attributes
   WifiDevice(const std::string &_ip_addr = "",
              const std::string &_mac_addr = "",
              const float &_antenna_gain = WIFIDEVICE_DEFAULT_ANTENNA_GAIN,
              const float &_trx_power = WIFIDEVICE_DEFAULT_TRX_POWER) ;
+  /// Copy constructor
   WifiDevice(const WifiDevice &wd) ;
 
-  ~WifiDevice() {}
+  ~WifiDevice(void) {} ///< Destructor (do nothing)
 
+  /** @name Read accessors */
+  //@{
+  /// #ip_addr read accessor
   const std::string& get_ip_addr(void) const ;
+  /// #mac_addr read accessor
   const std::string& get_mac_addr(void) const ;
+  /// #antenna_gain read accessor
   float get_antenna_gain(void) const ;
+  /// #trx_power read accessor
   float get_trx_power(void) const ;
+  //@}
 
+  /** @name Write accessors */
+  //@{
+  /// #ip_addr write accessor
   void set_ip_addr(const std::string &_ip_addr) ;
+  /// #mac_addr write accessor
   void set_mac_addr(const std::string &_mac_addr) ;
+  /// #antenna_gain write accessor
   void set_antenna_gain(float &_antenna_gain) ;
+  /// #trx_power write accessor
   void set_trx_power(float &_trx_power) ;
+  //@}
 
+  /** @name Operators */
+  //@{
   const WifiDevice& operator=(const WifiDevice &wd) ;
   bool operator==(const WifiDevice &wd) const ;
   bool operator!=(const WifiDevice &wl) const ;
+  //@}
 
+  /// Displays a WifiDevice
   friend std::ostream &operator<<(std::ostream &os, const WifiDevice &wd) ;
 } ;
 
 
 
-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */
 
 
 inline const std::string& WifiDevice::get_ip_addr() const
@@ -73,7 +98,7 @@ inline float WifiDevice::get_trx_power() const
 
 
 
-/*** Accesseurs écriture ***/
+/* *** Write accessors *** */
 
 
 inline void WifiDevice::set_ip_addr(const std::string &_ip_addr)
@@ -101,7 +126,7 @@ inline void WifiDevice::set_trx_power(float &_trx_power)
 
 
 
-/*** Opérateurs ***/
+/* *** Operators *** */
 
 
 inline bool WifiDevice::operator!=(const WifiDevice &wd) const