[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).
2010-01-16 12:23:07 +01:00 · 2010-01-16 12:23:07 +01:00 · 1f1d7de4f5
parent ab3302ff28
commit 1f1d7de4f5
34 changed files with 2184 additions and 184 deletions
--- a/owlps-positioning/.gitignore
+++ b/owlps-positioning/.gitignore
@ -0,0 +1,2 @@
+doc
+csv/*.csv
--- a/owlps-positioning/Doxyfile
+++ b/owlps-positioning/Doxyfile
--- a/owlps-positioning/Makefile
+++ b/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) && \
--- a/owlps-positioning/TODO
+++ b/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
--- a/owlps-positioning/accesspoint.cc
+++ b/owlps-positioning/accesspoint.cc
@ -5,7 +5,7 @@ using namespace std ;



-/*** Opérateurs ***/
+/* *** Operators *** */


 const AccessPoint& AccessPoint::operator=(const AccessPoint &ap)
--- a/owlps-positioning/accesspoint.hh
+++ b/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 ;
-  unsigned int frequency ; // Frequency (channel) in Hz
+  Point3D coordinates ; ///< Coordinates of the AccessPoint
+  unsigned int frequency ; ///< Frequency (channel) in Hz

 public:
-  AccessPoint(const WifiDevice &wd,
-              const Point3D &_coordinates,
-              const unsigned int &_frequency = AP_DEFAULT_CHANNEL):
-    WifiDevice(wd), coordinates(_coordinates), frequency(_frequency) {}
+  /// \brief Constructs an AccessPoint by defining all of its
+  /// attributes (or default constructor)
  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) ;
-  void set_frequency(unsigned int &_frequency) ;
+  /** @name Write accessors */
+  //@{
+  /// #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
--- a/owlps-positioning/area.cc
+++ b/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 << ';'
--- a/owlps-positioning/area.hh
+++ b/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 ;
-  std::string name ;
-  Point3D p_min ;
-  Point3D p_max ;
+  Building *building ; ///< The Building in which the Area is
+  std::string name ; ///< Name of the Area
+  Point3D p_min ; ///< First coordinate of the Area
+  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 ;
-  const std::string& get_name(void) const ;
-  const Point3D& get_p_min(void) const ;
-  const Point3D& get_p_max(void) const ;
+  /** @name Read accessors */
+  //@{
+  Building* get_building(void) const ; ///< #building read accessor
+  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
--- a/owlps-positioning/building.cc
+++ b/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 in
- *   waypoints that belong only to this Building (waypoints that link)
- *   several buildings are preserved).
+/**
+ * Note: deletes (unallocates) all elements in #areas; deletes elements
+ * in #waypoints that belong only to this Building (waypoints that link
+ * several buildings are preserved).
 */
 Building::~Building()
 {
@ -52,7 +51,7 @@ Building::~Building()



-/*** Opérateurs ***/
+/* *** Operators *** */


 const Building& Building::operator=(const Building &b)
--- a/owlps-positioning/building.hh
+++ 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::vector<Area*> areas ;
-  std::vector<Waypoint*> waypoints ;
+  std::string name ; ///< Name of the Building
+  std::vector<Area*> areas ; ///< List of Area contained in the Building
+  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
--- a/owlps-positioning/calibrationmeasurement.cc
+++ b/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
--- a/owlps-positioning/calibrationmeasurement.hh
+++ b/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)
--- a/owlps-positioning/csv/.gitignore
+++ b/owlps-positioning/csv/.gitignore
@ -1 +0,0 @@
-*.csv
--- a/owlps-positioning/inputcsv.cc
+++ b/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)
--- a/owlps-positioning/inputcsv.hh
+++ b/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 ;
--- a/owlps-positioning/inputmedium.hh
+++ b/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 ;

-  /*
-   * Reads the next request and returns it, increments current_line
-   * Returns an empty Request in case of error or EOF (note that
-   * when casted in bool, an empty Request is false).
+  /// Checks if the last request has been reached
+  /**
+   * @return \em true if the last request has been reached.
+   * @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 ;

-  /*
-   * Returns true if the last request has been reached
-   */
-  virtual bool eof(void) const = 0 ;
+  //@} // End Operations
 } ;



-/*** Constructeurs ***/
+/* *** Constructors *** */


 inline InputMedium::InputMedium()
@ -40,7 +68,7 @@ inline InputMedium::InputMedium()



-/*** Accesseurs lecture ***/
+/* *** Read accessors *** */


 inline const Request& InputMedium::get_current_request() const
--- a/owlps-positioning/measurement.cc
+++ b/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 and mobile are not deleted, only initialised at NULL.
+/**
+ * - #ap is not deleted, only initialised to 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)
--- a/owlps-positioning/measurement.hh
+++ b/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
- * attribute is initialised.
+/**
+ * @return \em false if the Measurement is empty.
+ * @return \em true if at least one attribute is initialised.
 */
 inline Measurement::operator bool() const
 {
--- a/owlps-positioning/mobile.cc
+++ b/owlps-positioning/mobile.cc
@ -2,7 +2,7 @@



-/*** Opérateurs ***/
+/* *** Operators *** */


 const Mobile& Mobile::operator=(const Mobile &m)
--- a/owlps-positioning/mobile.hh
+++ b/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
--- a/owlps-positioning/point3d.cc
+++ b/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)
--- a/owlps-positioning/point3d.hh
+++ b/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 y ;
-  float z ;
+  float x ; ///< X horizontal coordinate (abscissa)
+  float y ; ///< Y horizontal coordinate (ordinate)
+  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 ;
-  float get_y(void) const ;
-  float get_z(void) const ;
+  /** @name Read accessors */
+  //@{
+  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) ;
-  void set_y(const float &_y) ;
-  void set_z(const float &_z) ;
-  void set_coordinates(const Point3D &p) ;
+  /** @name Write accessors */
+  //@{
+  void set_x(const float &_x) ; ///< #x write accessor
+  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 : pour comparer deux distances, utiliser de préférence
- *        square_distance, qui fait économiser une racine carrée.
+/**
+ * Note: to compare distances, use preferably square_distance(),
+ * which is more efficient.
 */
 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 : pour comparer deux distances, utiliser de préférence
- *        square_distance, qui fait économiser une racine carrée.
+/**
+ * Note: to compare distances, use preferably square_distance(),
+ * which is more efficient.
 */
 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
--- a/owlps-positioning/posutil.cc
+++ b/owlps-positioning/posutil.cc
@ -2,9 +2,11 @@



-/*
- * Returns the frequency in Hz corresponding to the 802.11 channel "channel"
- * or 0 if the channel is wrong.
+/**
+ * @param channel A IEEE 802.11 channel.
+ * @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)
 {
--- a/owlps-positioning/posutil.hh
+++ b/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_
--- a/owlps-positioning/referencepoint.cc
+++ b/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)
--- a/owlps-positioning/referencepoint.hh
+++ b/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
--- a/owlps-positioning/request.cc
+++ b/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)
--- a/owlps-positioning/request.hh
+++ b/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
- * attribute is initialised.
+/**
+ * @return \em false if the Request is empty.
+ * @return \em true if at least one attribute is initialised.
 */
 inline Request::operator bool() const
 {
--- a/owlps-positioning/stock.cc
+++ b/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 + " »!") ;
+}
--- a/owlps-positioning/stock.hh
+++ b/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 ***/
-
-
-inline const Mobile& Stock::get_mobile(const std::string &mac)
-{
-  return mobiles[mac] ;
-}
+/* *** Read accessors *** */


+/**
+ * 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)
-{
-  return aps[mac] ;
-}
-
-
+/**
+ * If the AccessPoint corresponding to \em mac does not exist, it is
+ * 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] ;
--- a/owlps-positioning/waypoint.cc
+++ b/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)
--- a/owlps-positioning/waypoint.hh
+++ b/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,
-           const float &_z = 0) ;
+  /// \brief Constructs a Waypoint from a Building pointer and a
+  /// 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
--- a/owlps-positioning/wifidevice.cc
+++ b/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)
--- a/owlps-positioning/wifidevice.hh
+++ b/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 mac_addr ;
-  float antenna_gain ; // Antenna gain in dBi
-  float trx_power ; // Transmit power in dBm
+  std::string ip_addr ; ///< IP address
+  std::string mac_addr ; ///< MAC address
+  float antenna_gain ; ///< Antenna gain in dBi
+  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