[Positioner] Use Markdown in Doxygen comments

Fix some comments as well, and uniformise the use of @returns instead of
@return.

owlps-positioner/src/accesspoint.cc

@@ -33,9 +33,9 @@ double AccessPoint::friis_constant_term() const
 
 /**
  * @param trx The transmitter AP.
- * @returns The percentage of calibration packets sent by \em trx and
+ * @returns The percentage of calibration packets sent by `trx` and
  * received by the AP.
- * @returns 0 if no packet were received from \em trx.
+ * @returns 0 if no packet were received from `trx.`
  */
 float AccessPoint::
 received_calibration_from_ap(const AccessPoint &trx) const

owlps-positioner/src/accesspoint.hh

@@ -22,7 +22,8 @@
 #define AP_DEFAULT_CHANNEL 6
 #define AP_DEFAULT_ANTENNA_GAIN 5
 
-/// Represents a capture \link WifiDevice Wi-Fi device\endlink
+/// \brief Represents a [Wi-Fi device](@ref WifiDevice) used for
+/// capturing requests
 class AccessPoint: public WifiDevice
 {
 protected:
@@ -33,9 +34,9 @@ protected:
 public:
   /**
    * Special parameters:
-   * - \em _antenna_gain Antenna gain in dBi.
+   * - `_antenna_gain` Antenna gain in dBi.
-   * - \em _trx_power Transmit power in dBm.
+   * - `_trx_power` Transmit power in dBm.
-   * - \em channel Wi-Fi channel the AP is listening to (integer
+   * - `channel` Wi-Fi channel the AP is listening to (integer
    * between 1 and 14). It will be converted to a frequency in Hz.
    */
   AccessPoint(const Point3D &_coordinates = Point3D(),
@@ -86,7 +87,7 @@ public:
   /// Returns the Friis formula's constant term
   double friis_constant_term(void) const ;
   /// \brief Computes the percentage of the calibration packets from
-  /// \em trx received by the AP
+  /// `trx` received by the AP
   float received_calibration_from_ap(const AccessPoint &trx) const ;
   //@}
 
@@ -146,7 +147,7 @@ inline void AccessPoint::set_channel(const unsigned int channel)
 
 
 /**
- * Sets #frequency with the value of the parameter \em _frequency. No
+ * Sets #frequency with the value of the parameter `_frequency.` No
  * control is done, so you should pass a correct value.
  *
  * Note that set_channel() is more secure because a wrong channel

owlps-positioner/src/area.cc

@@ -36,8 +36,8 @@ Area::Area(const Building *_building, const string &_name,
 
 
 /**
- * @return \em true if \em p is into the Area.
+ * @returns `true` if `p` is into the Area.
- * @return \em false if \em p is not into the Area.
+ * @returns `false` if `p` is not into the Area.
  */
 bool Area::contains_point(const Point3D &p) const
 {

owlps-positioner/src/building.hh

@@ -54,9 +54,9 @@ public :
   /** @name Write accessors */
   //@{
   void set_name(const std::string &_name) ;
-  /// Adds an Area to the \link #areas list of areas\endlink
+  /// Adds an Area to the [list of areas](@ref #areas)
   void add_area(Area *&a) ;
-  /// Adds a Waypoint to the \link #waypoints list of waypoints\endlink
+  /// Adds a Waypoint to the [list of waypoints](@ref #waypoints)
   void add_waypoint(const Waypoint *wp) ;
   //@}
 
@@ -107,7 +107,7 @@ inline void Building::set_name(const std::string &_name)
 
 
 /**
- * @param wp A pointer to the Waypoint to add. If \em wp is NULL,
+ * @param wp A pointer to the Waypoint to add. If `wp` is NULL,
  * nothing will be added.
  */
 inline void Building::add_waypoint(const Waypoint *wp)

owlps-positioner/src/configuration.cc

@@ -74,8 +74,8 @@ bool Configuration::bool_value(const string &key)
 
 
 /**
- * @return \em true if the string \em value exists in the vector \em key.
+ * @returns `true` if the string `value` exists in the vector `key.`
- * @return \em false if \em value is not found in \em key.
+ * @returns `false` if `value` is not found in `key.`
  */
 bool Configuration::
 value_exists_in_string_vector(const string &key, const string &value)

owlps-positioner/src/configuration.hh

@@ -37,21 +37,21 @@ public:
 
   /** @name Type-specific accessors */
   //@{
-  /// Returns the string value corresponding to \em key
+  /// Returns the string value corresponding to `key`
   static const std::string& string_value(const std::string &key) ;
-  /// Returns the int value corresponding to \em key
+  /// Returns the int value corresponding to `key`
   static int int_value(const std::string &key) ;
-  /// Returns the unsigned int value corresponding to \em key
+  /// Returns the unsigned int value corresponding to `key`
   static unsigned int uint_value(const std::string &key) ;
-  /// Returns the float value corresponding to \em key
+  /// Returns the float value corresponding to `key`
   static float float_value(const std::string &key) ;
-  /// Returns the bool value corresponding to \em key
+  /// Returns the bool value corresponding to `key`
   static bool bool_value(const std::string &key) ;
-  /// Checks if a given string value exists in \em key
+  /// Checks if a given string value exists in `key`
   static bool value_exists_in_string_vector(
     const std::string &key,
     const std::string &value) ;
-  /// Returns the vector value corresponding to \em key
+  /// Returns the vector value corresponding to `key`
   static const std::vector<std::string>&
   string_vector_value(const std::string &key) ;
   //@}

owlps-positioner/src/csvfilereader.cc

@@ -27,7 +27,7 @@ using namespace std ;
 /**
  * Note that this function is not called by the constructor, so you
  * must manually call it prior to use read_field().
- * @return \em false in case of error (EOF, etc.), \em true else.
+ * @returns `false` in case of error (EOF, etc.), `true` else.
  */
 bool CSVFileReader::next_line()
 {

owlps-positioner/src/csvstringreader.cc

@@ -46,7 +46,7 @@ CSVStringReader::~CSVStringReader()
 
 
 /**
- * @returns \em false in case of error (EOF, etc.), \em true else.
+ * @returns `false` in case of error (EOF, etc.), `true` else.
  */
 void CSVStringReader::set_str(const string &_str)
 {

owlps-positioner/src/inputcsv.cc

@@ -34,8 +34,8 @@ using namespace std ;
  * Blank lines and lines containing only spaces are skipped until a line
  * containing a request is found.
  *
- * @returns \em true if #current_request was correctly filled.
+ * @returns `true` if #current_request was correctly filled.
- * @returns \em false in case of error (file not opened, end of file,
+ * @returns `false` in case of error (file not opened, end of file,
  * invalid field or wrong number of fields in the line).
  */
 bool InputCSV::fill_current_request()

owlps-positioner/src/inputcsv.hh

@@ -20,7 +20,7 @@
 
 #include <string>
 
-/// Reads \link Request requests \endlink from a CSV file
+/// Reads [requests](@ref Request) from a CSV file
 /**
  * CSV format is:
  *   Mobile_MAC;Request_type;Number_of_packets;Timestamp;X;Y;Z;Direction;

owlps-positioner/src/inputlogcsv.hh

@@ -18,7 +18,7 @@
 #include "inputlogmedium.hh"
 #include "textfilewriter.hh"
 
-/// Logs \link Request requests \endlink to a CSV file
+/// Logs [requests](@ref Request) to a CSV file
 /**
  * CSV format is the same as the one read by InputCSV.
  */

owlps-positioner/src/inputmedium.cc

@@ -47,11 +47,11 @@ InputMedium::~InputMedium()
  * and returns it.
  *
  * The input medium should be ready to be read before precessing
- * requests; otherwise, #current_request is \link Request::clear()
+ * requests; otherwise, #current_request is [cleared](@ref Request::clear)
- * cleared\endlink and a blank Request is returned.
+ * and a blank Request is returned.
  *
- * @return The Request read, or an empty Request in case of error or
+ * @returns The Request read, or an empty Request in case of error or
- * EOF (note that when casted to bool, an empty Request is \em false,
+ * EOF (note that when casted to bool, an empty Request is `false`,
  * see Request::operator bool()).
  */
 const Request& InputMedium::get_next_request()
@@ -83,7 +83,7 @@ void InputMedium::clear_current_request()
 
 
 /**
- * The \em position argument can be changed by this function.
+ * The `position` argument can be changed by this function.
  */
 void InputMedium::
 fill_calibration_request_data(const string &mac_mobile, Point3D &position,

owlps-positioner/src/inputmedium.hh

@@ -60,8 +60,8 @@ public:
 
   /// Checks if the last request has been reached
   /**
-   * @return \em true if the last request has been reached.
+   * @returns `true` if the last request has been reached.
-   * @return \em false if there is something more to read.
+   * @returns `false` if there is something more to read.
    */
   virtual bool eof(void) const = 0 ;
 

owlps-positioner/src/inputudpsocket.cc

@@ -51,8 +51,8 @@ InputUDPSocket::~InputUDPSocket()
 
 
 /**
- * @return \em true if the socket were successfully opened.
+ * @returns `true` if the socket were successfully opened.
- * @return \em false in case of error.
+ * @returns `false` in case of error.
  */
 bool InputUDPSocket::init_socket()
 {
@@ -65,9 +65,9 @@ bool InputUDPSocket::init_socket()
  * Normally, the socket is closed automatically by the destructor. Use
  * this if you want to close the socket prematurely.
  * #sockfd is set to -1, even in case of error.
- * @return \em true if the socket were successfully closed or were not
+ * @returns `true` if the socket were successfully closed or were not
  * opened.
- * @return \em false in case of error.
+ * @returns `false` in case of error.
  */
 bool InputUDPSocket::close_socket()
 {
@@ -89,8 +89,8 @@ bool InputUDPSocket::close_socket()
 /**
  * This function fills the current Request from the UDP input socket.
  *
- * @returns \em true if #current_request was correctly filled.
+ * @returns `true` if #current_request was correctly filled.
- * @returns \em false in case of error (socket not opened, bad packet
+ * @returns `false` in case of error (socket not opened, bad packet
  * format).
  */
 bool InputUDPSocket::fill_current_request()

owlps-positioner/src/inputudpsocket.hh

@@ -17,7 +17,7 @@
 
 #include "inputmedium.hh"
 
-/// Receives \link Request requests \endlink from a UDP socket
+/// Receives [requests](@ref Request) from a UDP socket
 class InputUDPSocket: public InputMedium
 {
 protected:
@@ -33,8 +33,8 @@ protected:
    * This function fills the current Request from the data read from
    * the input medium.
    *
-   * @returns \em true if #current_request was correctly filled.
+   * @returns `true` if #current_request was correctly filled.
-   * @returns \em false in case of error.
+   * @returns `false` in case of error.
    */
   bool fill_current_request(void) ;
   //@}
@@ -64,8 +64,8 @@ public:
 
 /**
  * Note that by definition, the end of a socket is never reached.
- * @return \em true if the socket is closed.
+ * @returns `true` if the socket is closed.
- * @return \em false if the socket is opened.
+ * @returns `false` if the socket is opened.
  */
 inline bool InputUDPSocket::eof() const
 {

owlps-positioner/src/measurement.cc

@@ -40,7 +40,7 @@ Measurement::~Measurement()
 
 
 /**
- * @returns The SS of the packet number \em pkt_id.
+ * @returns The SS of the packet number `pkt_id.`
  * @returns 0 if the packet ID does not exist in the SS list.
  */
 ss_t Measurement::get_ss(pkt_id_t pkt_id) const
@@ -98,7 +98,7 @@ add_ss_list(const map<pkt_id_t, ss_t> &_ss_list)
 
 
 /**
- * Merge consists of adding the SS values of \em source to #ss_list. It
+ * Merge consists of adding the SS values of `source` to #ss_list. It
  * is possible only if the #ap of the two Measurement are identical.
  * @throw cannot_merge if the AP of the two Measurement are different.
  */

owlps-positioner/src/measurement.hh

@@ -82,7 +82,7 @@ public:
   //@{
   /// Returns the AccessPoint associated with the Measurement
   AccessPoint* get_ap() const ;
-  /// Returns the packet number \em pkt_id
+  /// Returns the packet number `pkt_id`
   ss_t get_ss(pkt_id_t pkt_id) const ;
   /// Returns the mean of the SS list, in dBm
   float get_average_dbm() const ;
@@ -235,8 +235,8 @@ inline bool Measurement::operator!=(const Measurement &m) const
 
 
 /**
- * @return \em false if the Measurement is empty.
+ * @returns `false` if the Measurement is empty.
- * @return \em true if at least one attribute is initialised.
+ * @returns `true` if at least one attribute is initialised.
  */
 inline Measurement::operator bool() const
 {

owlps-positioner/src/mobile.hh

@@ -21,7 +21,7 @@
 
 #define MOBILE_DEFAULT_ANTENNA_GAIN 2
 
-/// \brief Represents a mobile \link WifiDevice Wi-Fi device\endlink
+/// \brief Represents a mobile [Wi-Fi device](@ref WifiDevice)
 /// that can be localised
 class Mobile: public WifiDevice
 {

owlps-positioner/src/outputnetworksocket.cc

@@ -41,9 +41,9 @@ OutputNetworkSocket::~OutputNetworkSocket()
  * Normally, the socket is closed automatically by the destructor. Use
  * this if you want to close the socket prematurely.
  * #sockfd is set to -1, even in case of error.
- * @return \em true if the socket were successfully closed or were not
+ * @returns `true` if the socket were successfully closed or were not
  * opened.
- * @return \em false in case of error.
+ * @returns `false` in case of error.
  */
 bool OutputNetworkSocket::close_socket()
 {

owlps-positioner/src/outputtcpsocketevaal.cc

@@ -46,8 +46,8 @@ OutputTCPSocketEvAAL(const string &_remote_host,
 
 
 /**
- * @return \em true if the socket were successfully opened.
+ * @returns `true` if the socket were successfully opened.
- * @return \em false in case of error.
+ * @returns `false` in case of error.
  */
 bool OutputTCPSocketEvAAL::init_socket()
 {

owlps-positioner/src/outputudpsocket.cc

@@ -43,8 +43,8 @@ OutputUDPSocket::OutputUDPSocket(const string &_remote_host,
 
 
 /**
- * @return \em true if the socket were successfully opened.
+ * @returns `true` if the socket were successfully opened.
- * @return \em false in case of error.
+ * @returns `false` in case of error.
  */
 bool OutputUDPSocket::init_socket()
 {

owlps-positioner/src/point3d.cc

@@ -178,8 +178,8 @@ Point3D::operator std::string(void) const
 
 
 /**
- * @return \em true if either #x, #y or #z is non-zero.
+ * @returns `true` if either #x, #y or #z is non-zero.
- * @return \em false if #x, #y and #z are defined to 0.
+ * @returns `false` if #x, #y and #z are defined to 0.
  */
 Point3D::operator bool(void) const
 {

owlps-positioner/src/positioning.hh

@@ -22,9 +22,8 @@ class PositioningAlgorithm ;
 
 #include <vector>
 
-/// \brief Computes \link Result results \endlink from \link Request
+/// \brief Computes [results](@ref Result) from [requests](@ref Request)
-/// requests \endlink using one or more \link PositioningAlgorithm
+/// using one or more [positioning algorithms](@ref PositioningAlgorithm)
-/// positioning algorithms \endlink
 class Positioning
 {
 protected:

owlps-positioner/src/posutil.cc

@@ -118,8 +118,8 @@ float PosUtil::similarity(
 
 /**
  * @param channel A IEEE 802.11 channel or frequency in MHz or in Hz.
- * @return The frequency in Hz.
+ * @returns The frequency in Hz.
- * @throw malformed_input_data if \em channel is not a valid channel or
+ * @throw malformed_input_data if `channel` is not a valid channel or
  * frequency value.
  */
 unsigned long PosUtil::wifi_channel_to_hz(const unsigned long &channel)

owlps-positioner/src/posutil.hh

@@ -36,11 +36,11 @@ public:
 
   /** @name Maths */
   //@{
-  /// Returns the radian value of \em degrees
+  /// Returns the radian value of `degrees`
   static double deg2rad(const double &degrees) ;
-  /// Returns the degree value of \em radians
+  /// Returns the degree value of `radians`
   static double rad2deg(const double &radians) ;
-  /// Checks if \em value is in the interval [center-width;center+width]
+  /// Checks if `value` is in the interval [center-width;center+width]
   static bool is_in_interval(float center, float bound, float value) ;
   //@}
 
@@ -87,15 +87,15 @@ hash_combine(std::size_t &seed, const T &v)
 
 
 /**
- * This function checks if \em value belongs to the symmetrical interval
+ * This function checks if `value` belongs to the symmetrical interval
  * [center-bound;center+bound].
  *
  * @arg center The center of the interval.
  * @arg bound Half the width of the interval.
  * @arg value The value to check the presence in the interval.
  *
- * @returns \em true if value belongs to the interval.
+ * @returns `true` if value belongs to the interval.
- * @returns \em false if value does not belong to the interval.
+ * @returns `false` if value does not belong to the interval.
  */
 inline bool PosUtil::
 is_in_interval(float center, float bound, float value)

owlps-positioner/src/referencepoint.cc

@@ -103,7 +103,7 @@ get_all_measurements(const string &mac_transmitter) const
 /**
  * @param mac_transmitter The MAC address of the transmitting mobile.
  *
- * @return A vector containing all the requests sent by the mobile.
+ * @returns A vector containing all the requests sent by the mobile.
  * The returned vector is empty if no request was sent by the mobile.
  */
 const vector<CalibrationRequest*> ReferencePoint::
@@ -161,8 +161,8 @@ void ReferencePoint::delete_requests()
  * Note that the requests pointed by the elements of #requests are
  * actually deleted from the Stock.
  *
- * @returns \em true if at least one request was deleted.
+ * @returns `true` if at least one request was deleted.
- * @returns \em false if the ReferencePoint was left untouched.
+ * @returns `false` if the ReferencePoint was left untouched.
  */
 bool ReferencePoint::delete_generated_requests(void)
 {
@@ -306,7 +306,7 @@ float ReferencePoint::friis_indexes_for_ap(
 
 /**
  * Computes a Friis index for the distance AP-ReferencePoint, based on a
- * given packet (\em pkt_id), of a measurement of this AP present in the
+ * given packet (`pkt_id),` of a measurement of this AP present in the
  * ReferencePoint. This measurement is the first found in the
  * ReferencePoint. This works well when we keep only one calibration
  * request per reference point.

owlps-positioner/src/referencepoint.hh

@@ -31,7 +31,7 @@ class ReferencePoint: public Point3D
 {
 protected:
   /// List of CalibrationRequest associated with the ReferencePoint
-  /** Note that \em requests is a \em pointer list: only pointers
+  /** Note that `requests` is a *pointer* list: only pointers
       are stored, not values. */
   std::vector<CalibrationRequest*> requests ;
 
@@ -64,15 +64,15 @@ public:
   const std::vector<CalibrationRequest*> get_requests(
     const std::string &mac_transmitter) const ;
   /// \brief Returns the average SS of all the packets sent by
-  /// \em mac_transmitter
+  /// `mac_transmitter`
   double average_measurements(const std::string &mac_transmitter) const ;
   //@}
 
   /** @name Write accessors */
   //@{
-  /// Adds a Request to the \link #requests request list\endlink
+  /// Adds a Request to the [requests' list](@ref #requests)
   void add_request(const CalibrationRequest *r) ;
-  /// Deletes a Request from the \link #requests request list\endlink
+  /// Deletes a Request from the [requests' list](@ref #requests)
   void delete_request(const CalibrationRequest *r) ;
   /// Deletes all the requests contained in #requests
   void delete_requests(void) ;
@@ -127,7 +127,7 @@ std::vector<CalibrationRequest*>& ReferencePoint::get_requests() const
  * @param r A pointer to the CalibrationRequest 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
+ * the ReferencePoint destruction (do *not* pass a pointer to a local
  * variable!).
  */
 inline void ReferencePoint::add_request(const CalibrationRequest *r)

owlps-positioner/src/request.hh

@@ -43,7 +43,7 @@ protected:
   Timestamp time_received ;
   /// List of Measurement of the request
   /** Note that this is not a pointer list, values are actually stored.
-      The \em string parameter is the MAC address of the receiver AP. */
+      The `string` parameter is the MAC address of the receiver AP. */
   std::unordered_map<std::string, Measurement> measurements ;
   /// \brief Real coordinates of the request (normally unavailable for a
   /// standard positioning request)
@@ -83,7 +83,7 @@ public:
   /// Returns all the measurements
   const std::unordered_map<std::string, Measurement>&
   get_measurements(void) const ;
-  /// Returns the measurement made by the AP \em mac_receiver, if any
+  /// Returns the measurement made by the AP `mac_receiver,` if any
   const Measurement*
   get_measurement(const std::string &mac_receiver) const ;
   const Point3D* get_real_position(void) const ;
@@ -229,8 +229,8 @@ inline bool Request::operator!=(const Request &comp) const
 
 
 /**
- * @return \em false if the Request is empty.
+ * @returns `false` if the Request is empty.
- * @return \em true if at least one attribute (other than #type and
+ * @returns `true` if at least one attribute (other than #type and
  * #nb_packets) is initialised.
  */
 inline Request::operator bool() const

owlps-positioner/src/result.cc

@@ -99,7 +99,7 @@ bool Result::operator==(const Result &source) const
  * The format used is the following:
  *   Algorithm_name;X;Y;Z;Error;Area_name
  *
- * @return The result as a CSV string, \em without a trailing '\\n'.
+ * @returns The result as a CSV string, *without* a trailing '\\n'.
  */
 const string Result::to_csv() const
 {

owlps-positioner/src/resultlist.cc

@@ -68,7 +68,7 @@ bool ResultList::operator==(const ResultList &source) const
  * The CSV format for the [Algorithm_i] strings is documented in
  * Result::to_csv().
  *
- * @return The results as a CSV string, \em without a trailing '\\n'.
+ * @returns The results as a CSV string, *without* a trailing '\\n'.
  */
 const string ResultList::to_csv() const
 {

owlps-positioner/src/resultlist.hh

@@ -21,8 +21,8 @@ class Request ;
 #include <vector>
 #include <ostream>
 
-/// \brief List of \link Result results \endlink of a single Request,
+/// \brief List of [results](@ref Result) of a single Request, computed
-/// computed by one or more positioning algorithm
+/// by one or more positioning algorithm
 class ResultList
 {
 protected:

owlps-positioner/src/stock.cc

@@ -78,9 +78,9 @@ const Building& Stock::find_create_building(const string &name)
 /**
  * @param name The name of the Building to search for.
  * It must be a valid name, as no check is performed.
- * @return A const reference to the Building.
+ * @returns A const reference to the Building.
  * @throw element_not_found is thrown if the Building corresponding
- * to \em name does not exist.
+ * to `name` does not exist.
  */
 const Building& Stock::get_building(const string &name)
 {
@@ -93,8 +93,8 @@ const Building& Stock::get_building(const string &name)
 
 
 /**
- * @returns A pointer to the first Area in which \em point was found.
+ * @returns A pointer to the first Area in which `point` was found.
- * @returns NULL if \em point does not belong to any Area.
+ * @returns NULL if `point` does not belong to any Area.
  */
 const Area* Stock::in_which_area_is(const Point3D &point)
 {
@@ -153,8 +153,8 @@ void Stock::waypoint_remove_building(const Waypoint &point,
 /**
  * @param mac The MAC address of the Mobile to search for.
  * It must be a valid MAC address, as no check is performed.
- * @return \em true if a mobile with this MAC address exists.
+ * @returns `true` if a mobile with this MAC address exists.
- * @return \em false if this MAC address was not found.
+ * @returns `false` if this MAC address was not found.
  */
 bool Stock::mobile_exists(const std::string &mac)
 {
@@ -166,9 +166,9 @@ bool Stock::mobile_exists(const std::string &mac)
 /**
  * @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.
+ * @returns A const reference to the Mobile.
  * @throw element_not_found is thrown if the Mobile corresponding
- * to \em mac does not exist.
+ * to `mac` does not exist.
  */
 const Mobile& Stock::get_mobile(const string &mac)
 {
@@ -196,7 +196,7 @@ const Mobile& Stock::find_create_mobile(const string &mac)
 
 
 /**
- * If the Mobile already exists, it is replaced by the \em source.
+ * If the Mobile already exists, it is replaced by `source.`
  */
 const Mobile& Stock::find_create_mobile(const Mobile &source)
 {
@@ -217,8 +217,8 @@ const Mobile& Stock::find_create_mobile(const Mobile &source)
 /**
  * @param mac The MAC address of the AccessPoint to search for.
  * It must be a valid MAC address, as no check is performed.
- * @return \em true if an AP with this MAC address exists.
+ * @returns `true` if an AP with this MAC address exists.
- * @return \em false if this MAC address was not found.
+ * @returns `false` if this MAC address was not found.
  */
 bool Stock::ap_exists(const std::string &mac)
 {
@@ -230,9 +230,9 @@ bool Stock::ap_exists(const std::string &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.
+ * @returns A const reference to the AccessPoint.
  * @throw element_not_found is thrown if the AccessPoint corresponding
- * to \em mac does not exist.
+ * to `mac` does not exist.
  */
 const AccessPoint& Stock::get_ap(const string &mac)
 {
@@ -266,7 +266,7 @@ const AccessPoint& Stock::find_create_ap(const string &mac)
 
 
 /**
- * If the AccessPoint already exists, it is replaced by the \em source.
+ * If the AccessPoint already exists, it is replaced by `source.`
  */
 const AccessPoint& Stock::find_create_ap(const AccessPoint &source)
 {
@@ -327,8 +327,8 @@ double Stock::ap_matrix_get_ss(const std::string &mac_transmitter,
 
 
 /**
- * @returns \em true if \em coord are the coordinates of an existing
+ * @returns `true` if `coord` are the coordinates of an existing
- * AP, \em false if not.
+ * AP, `false` if not.
  */
 bool Stock::is_ap_coordinate(const Point3D &coord)
 {
@@ -355,7 +355,7 @@ bool Stock::reference_point_exists(const ReferencePoint &point)
 
 /**
  * @param point Coordinates of the wanted ReferencePoint.
- * @return The ReferencePoint at the given coordinates, if found.
+ * @returns The ReferencePoint at the given coordinates, if found.
  * @throw element_not_found is thrown if no ReferencePoint exists at the
  * given coordinates.
  */

owlps-positioner/src/stock.hh

@@ -79,7 +79,7 @@ public:
   static const Building& get_building(const std::string &name) ;
   /// Searches for a Building and creates it if it does not exist
   static const Building& find_create_building(const std::string &name) ;
-  /// Searches the Area in which \em point is
+  /// Searches the Area in which `point` is
   static const Area* in_which_area_is(const Point3D &point) ;
   //@}
 
@@ -180,7 +180,7 @@ public:
   static void delete_calibration_request(
     const CalibrationRequest &request) ;
   /// \brief Deletes the calibration requests that are older than
-  /// \em timeout seconds
+  /// `timeout` seconds
   static void delete_calibration_requests_older_than(int timeout) ;
   /// Searches for a CalibrationRequest and adds it if it does not exist
   static const CalibrationRequest&
@@ -238,10 +238,10 @@ inline unsigned int Stock::nb_mobiles()
 
 
 /**
- * If the Mobile corresponding to \em mac does not exist, it is created.
+ * If the Mobile corresponding to `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.
+ * @returns A modifiable reference to the Mobile.
  */
 inline Mobile& Stock::getw_mobile(const std::string &mac)
 {
@@ -267,11 +267,11 @@ std::unordered_map<std::string, AccessPoint>& Stock::get_aps()
 
 
 /**
- * If the AccessPoint corresponding to \em mac does not exist, it is
+ * If the AccessPoint corresponding to `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.
+ * @returns A modifiable reference to the AccessPoint.
  */
 inline AccessPoint& Stock::getw_ap(const std::string &mac)
 {

owlps-positioner/src/textfilereader.cc

@@ -64,7 +64,7 @@ TextFileReader::~TextFileReader()
  * If the first non-blank character of a line is a #, then the line is
  * skipped (note that comments at the end of a line are *not* handled).
  * @param text Output argument; unchanged in case of error.
- * @return \em false in case of error, \em true else.
+ * @returns `false` in case of error, `true` else.
  */
 bool TextFileReader::read_nonblank_line(string &text)
 {
@@ -85,7 +85,7 @@ bool TextFileReader::read_nonblank_line(string &text)
 
 
 /**
- * @return The string read, or an empty string in case of error.
+ * @returns The string read, or an empty string in case of error.
  */
 bool TextFileReader::read_line(string &text)
 {
@@ -101,9 +101,9 @@ bool TextFileReader::read_line(string &text)
 /**
  * Tests if #file is opened and there is something more to
  * read. If the end of file is reached, the stream is closed.
- * @return \em true if the end of file is reached or if the file is
+ * @returns `true` if the end of file is reached or if the file is
  * already closed.
- * @return \em false if there is something more to read.
+ * @returns `false` if there is something more to read.
  */
 bool TextFileReader::eof_close()
 {

owlps-positioner/src/textfilereader.hh

@@ -57,8 +57,8 @@ public:
 
 
 /**
- * @return \em true if the end of file is reached.
+ * @returns `true` if the end of file is reached.
- * @return \em false if there is something more to read.
+ * @returns `false` if there is something more to read.
  */
 inline bool TextFileReader::eof() const
 {

owlps-positioner/src/textfilewriter.cc

@@ -61,8 +61,8 @@ TextFileWriter::~TextFileWriter()
 
 
 /**
- * @return \em true if the string has been written successfuly, or
+ * @returns `true` if the string has been written successfuly, or
- * \em false if not.
+ * `false` if not.
  */
 bool TextFileWriter::write_text(const string &text)
 {

owlps-positioner/src/timestamp.hh

@@ -82,7 +82,7 @@ public:
   bool now(void) ;
   /// Returns the time elapsed until now
   Timestamp elapsed(void) const ;
-  /// Returns the time elapsed since or until \em source
+  /// Returns the time elapsed since or until `source`
   Timestamp elapsed(const Timestamp &source) const ;
   /// Resets #timestamp
   void clear(void) ;

owlps-positioner/src/userinterface.cc

@@ -48,7 +48,7 @@ namespace po = boost::program_options ;
 
 
 /**
- * \em argc and \em argv are (normally) the ones passed to the main()
+ * `argc` and `argv` are (normally) the ones passed to the main()
  * function.
  * @param argc Number of arguments passed to the program.
  * @param argv Values of the arguments.

owlps-positioner/src/waypoint.hh

@@ -26,9 +26,9 @@ class Building ;
 /// 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
+ * it belongs to. You *should* always construct a Waypoint with at least
- * one associated Building, but you \em can not do so, for instance in an
+ * one associated Building, but you *can* do otherwise if needed, for
- * automatic construction (container…).
+ * instance in an automatic construction (container…).
  */
 class Waypoint: public Point3D
 {
@@ -57,9 +57,9 @@ public:
 
   /** @name Write accessors */
   //@{
-  /// Adds a Building to the \link #buildings building list\endlink
+  /// Adds a Building to the [buildings' list](@ref #buildings)
   void add_building(const Building *_b) ;
-  /// Adds the Building list of \em source to #buildings
+  /// Adds the Building list of `source` to #buildings
   void add_buildings(const Waypoint &source) ;
   /// Removes a Building from #buildings
   void remove_building(const Building *_b) ;
@@ -83,7 +83,7 @@ public:
 
 
 /**
- * @return A pointer to the first Building associated with the Waypoint
+ * @returns A pointer to the first Building associated with the Waypoint
  * (i.e. the first element of #buildings). If #buildings is empty, NULL
  * is returned.
  */
@@ -110,7 +110,7 @@ Waypoint::get_buildings() const
  * @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
+ * the Waypoint destruction (do *not* pass a pointer to a local
  * variable!).
  */
 inline void Waypoint::add_building(const Building *_b)

owlps-positioner/src/wifidevice.hh

@@ -23,7 +23,7 @@
 #define WIFIDEVICE_DEFAULT_ANTENNA_GAIN 2
 #define WIFIDEVICE_DEFAULT_TRX_POWER 20 // 20 dBm = 100 mW
 
-/// Represents a Wi-Fi enabled device
+/// Represents a Wi-Fi-enabled device
 /**
  * This class is virtual by design, you should derive it to create new
  * types of Wi-Fi devices.