[Positioner] Cosmetic changes, mainly comments

owlps-positioner/cfg/owlps-positioner.conf

@@ -242,7 +242,7 @@ mobile-csv-file = /usr/local/etc/owlps/mobiles.csv
 #udp-port = 9910
 
 # The TCPEvAAL output follows the specification of EvAAL 2011 to
-# communicate with the SocketAdapter program developped by the
+# communicate with the SocketAdapter program developed by the
 # organizers.
 # Note: you can use only one algorithm when using the TCPEvAAL output.
 #medium = TCPEvAAL

owlps-positioner/inputcsv.cc

@@ -135,7 +135,9 @@ bool InputCSV::fill_current_request()
       if (! read_field(packet_id, "the packet ID"))
         return false ;
 
-      int_fast16_t ss ;
+      // Note: the initialisation is useless but avoids a compilation
+      // warning.
+      int_fast16_t ss = 0 ;
       if (! read_field(ss, "the signal strength"))
         return false ;
 

owlps-positioner/inputmedium.cc

@@ -46,13 +46,15 @@ InputMedium::~InputMedium()
  * Reads a Request, increments current_line_nb, updates #current_request
  * and returns it.
  *
- * The input medium should be ready to be read before precessing
- * requests; otherwise, #current_request is [cleared](@ref Request::clear)
- * and a blank Request is returned.
+ * The input medium should be ready to be read before
+ * processing requests; otherwise, #current_request is
+ * [cleared](@ref Request::clear) and a blank Request is
+ * returned.
  *
- * @returns The Request read, or an empty Request in case of error or
- * EOF (note that when casted to bool, an empty Request is `false`,
- * see Request::operator bool()).
+ * @returns The Request read.
+ * @returns An empty Request in case of error or if the end of the
+ * file is reached (note that when casted to bool, an empty Request
+ * is `false`, see Request::operator bool()).
  */
 const Request& InputMedium::get_next_request()
 {

owlps-positioner/measurement.cc

@@ -100,6 +100,9 @@ add_ss_list(const map<pkt_id_t, ss_t> &_ss_list)
 /**
  * Merge consists of adding the SS values of `source` to #ss_list. It
  * is possible only if the #cp of the two Measurement are identical.
+ * Since add_ss_list() is used, if `source` contains packets with IDs
+ * that already exist, the old ones will be overwritten.
+ *
  * @throw cannot_merge if the CP of the two Measurement are different.
  */
 void Measurement::merge(const Measurement &source)

owlps-positioner/result.cc

@@ -27,6 +27,10 @@ using namespace std ;
 /* *** Constructors *** */
 
 
+/**
+ * The error (distance between _position and _real_position) is
+ * computed automatically.
+ */
 Result::Result(const Request *_request,
                const std::string &_algorithm,
                const Point3D &_position,

owlps-positioner/result.hh

@@ -58,6 +58,7 @@ public:
 
   /** @name Write accessors */
   //@{
+  /// Computes the distance between #position and `real_position`
   void compute_error(const Point3D &real_position) ;
   //@}
 

owlps-positioner/timestamp.cc

@@ -108,12 +108,11 @@ Timestamp Timestamp::get_current_time()
 
 
 /**
- * @param source A pointer to the new time. If NULL, #current_time is
- * updated to the current time.
+ * @param source A reference to the new time.
  */
 void Timestamp::update_current_time(const Timestamp &source)
 {
-  // We should never call this function if we are in replay mode:
+  // We should only call this function if we are in replay mode:
   assert(Configuration::bool_value("replay")) ;
 
   // According to human perception, time generally goes only forward:

owlps-positioner/userinterface.cc

@@ -54,11 +54,10 @@ namespace po = boost::program_options ;
  * @param argc Number of arguments passed to the program.
  * @param argv Values of the arguments.
  */
-UserInterface::UserInterface(const int argc, char **argv)
+UserInterface::UserInterface(const int argc, const char **const argv):
+  cli_argument_count(argc), cli_argument_values(argv)
 {
-  assert(argv) ;
-  cli_argument_values = argv ;
-  cli_argument_count = argc ;
+  assert(cli_argument_values) ;
 
   try
     {

owlps-positioner/wifidevice.hh

@@ -80,6 +80,9 @@ public:
 /* *** Constructors *** */
 
 
+/**
+ * `_mac_addr` must be uppercase.
+ */
 inline WifiDevice::
 WifiDevice(const std::string &_ip_addr,
            const std::string &_mac_addr,