API documentation improvements and minor refactorings.

adaptors/touchadaptor/touchadaptor.cpp

@@ -166,8 +166,8 @@ void TouchAdaptor::commitOutput(int src, struct input_event *ev)
     d->x_ = touchValues_[src].x;
     d->y_ = touchValues_[src].y;
     d->z_ = touchValues_[src].z;
-    d->tp_ = src;
-    d->st_ = touchValues_[src].fingerState;
+    d->object_ = src;
+    d->state_ = touchValues_[src].fingerState;
 
     outputBuffer_->commit();
     outputBuffer_->wakeUpReaders();

datatypes/compass.h

@@ -31,34 +31,32 @@
 #include <datatypes/orientationdata.h>
 
 /**
- * @brief Compass is a wrapper class for #CompassData.
- *
- * It is used for marshalling compass measurements over DBus.
+ * QObject facade for #CompassData.
  */
 class Compass : public QObject
 {
 public:
-    Q_OBJECT;
+    Q_OBJECT
 
-    Q_PROPERTY(int degrees READ degrees);
-    Q_PROPERTY(int level READ level);
+    Q_PROPERTY(int degrees READ degrees)
+    Q_PROPERTY(int level READ level)
 
 public:
 
     /**
-     * Default constructor (needed for Qt metatype system)
+     * Default constructor.
      */
     Compass() {}
 
     /**
-     * Copy constructor (needed for Qt metatype system)
+     * Copy constructor.
      *
      * @param data Source object.
      */
     Compass(const CompassData& data);
 
     /**
-     * Copy constructor (needed for Qt metatype system)
+     * Copy constructor.
      *
      * @param data Source object.
      */
@@ -110,9 +108,7 @@ class Compass : public QObject
 private:
     CompassData data_;
 
-    friend QDBusArgument &operator<<(QDBusArgument &argument, const Compass& data);
     friend const QDBusArgument &operator>>(const QDBusArgument &argument, Compass& data);
-    friend class CompassSensorChannel;
 };
 
 Q_DECLARE_METATYPE( Compass )
@@ -127,7 +123,7 @@ Q_DECLARE_METATYPE( Compass )
 inline QDBusArgument &operator<<(QDBusArgument &argument, const Compass &data)
 {
     argument.beginStructure();
-    argument << data.data_.timestamp_ << data.data_.degrees_ << data.data_.level_;
+    argument << data.data().timestamp_ << data.data().degrees_ << data.data().level_;
     argument.endStructure();
     return argument;
 }

datatypes/datarange.h

@@ -70,14 +70,9 @@ class DataRange : public QObject {
     DataRange(double min, double max, double resolution) :
         QObject(), min(min), max(max), resolution(resolution) {}
 
-    /* Range lower end */
-    double min;
-
-    /* Range higher end */
-    double max;
-
-    /* Range resolution */
-    double resolution;
+    double min;         /**< Range lower end */
+    double max;         /**< Range higher end */
+    double resolution;  /**< Range resolution */
 
     /**
      * Assignment operator.
@@ -255,11 +250,8 @@ class DataRangeRequest
 {
 public:
 
-    /* Request ID */
-    int       id;
-
-    /* Resuested range */
-    DataRange range;
+    int       id;     /**< Request ID */
+    DataRange range;  /**< Resuested range */
 
     /**
      * Constructor.
@@ -296,11 +288,8 @@ class DataRangeRequest
  */
 class IntervalRequest {
 public:
-    /* Request ID */
-    int      id;
-
-    /* Requested interval value */
-    unsigned value;
+    int      id;     /**< Request ID */
+    unsigned value;  /**< Requested interval value */
 
     /**
      * Constructor.

datatypes/genericdata.h

@@ -30,24 +30,30 @@
 #include <QMetaType>
 
 /**
- * A base class for measurements that contain timestamp.
+ * A base class for measurement data that contain timestamp.
  */
-class TimedData {
+class TimedData
+{
 public:
-    TimedData(quint64 timestamp) : timestamp_(timestamp) {}
 
-    quint64 timestamp_; /**< Timestamp value */
+    /**
+     * Constructor
+     *
+     * @param timestamp monotonic time (microsec)
+     */
+    TimedData(const quint64& timestamp) : timestamp_(timestamp) {}
+
+    quint64 timestamp_;  /**< monotonic time (microsec) */
 };
 
 /**
- * Class for vector type measurement data (timestamp, x, y, z). Can easily be
- * extended.
+ * Class for vector type measurement data (timestamp, x, y, z).
  */
 class TimedXyzData : public TimedData
 {
 public:
     TimedXyzData() : TimedData(0), x_(0), y_(0), z_(0) {}
-    TimedXyzData(quint64 timestamp, int x, int y, int z) : TimedData(timestamp), x_(x), y_(y), z_(z) {}
+    TimedXyzData(const quint64& timestamp, int x, int y, int z) : TimedData(timestamp), x_(x), y_(y), z_(z) {}
 
     int x_; /**< X value */
     int y_; /**< Y value */

datatypes/magneticfield.h

@@ -29,9 +29,11 @@
 #define MAGNETICFIELDDATA_H
 
 #include <QDBusArgument>
-
 #include <datatypes/orientationdata.h>
 
+/**
+ * QObject facade for #CalibratedMagneticField.
+ */
 class MagneticField : public QObject
 {
 public:
@@ -40,12 +42,14 @@ class MagneticField : public QObject
 public:
 
     /**
-     * Default constructor (needed for Qt metatype system)
+     * Default constructor.
      */
     MagneticField() : QObject() {}
 
     /**
-     * Copy constructor (needed for Qt metatype system)
+     * Constructor.
+     *
+     * @param calibratedData Source object.
      */
     MagneticField(const CalibratedMagneticFieldData& calibratedData) : QObject() {
         data_.timestamp_ = calibratedData.timestamp_;
@@ -55,11 +59,13 @@ class MagneticField : public QObject
         data_.z_ = calibratedData.z_;
         data_.rx_ = calibratedData.rx_;
         data_.ry_ = calibratedData.ry_;
-        data_.rz_ = calibratedData.rz_; 
+        data_.rz_ = calibratedData.rz_;
     }
 
     /**
-     * Copy constructor (needed for Qt metatype system)
+     * Copy constructor.
+     *
+     * @param data Source object.
      */
     MagneticField(const MagneticField& data) : QObject() {
         data_.timestamp_ = data.data_.timestamp_;
@@ -69,11 +75,21 @@ class MagneticField : public QObject
         data_.z_ = data.data_.z_;
         data_.rx_ = data.data_.rx_;
         data_.ry_ = data.data_.ry_;
-        data_.rz_ = data.data_.rz_; 
+        data_.rz_ = data.data_.rz_;
     }
 
+    /**
+     * Accessor for contained #CalibratedMagneticFieldData.
+     *
+     * @return contained #CalibratedMagneticFieldData.
+     */
     const CalibratedMagneticFieldData& data() const { return data_; }
 
+    /**
+     * Assignment operator.
+     *
+     * @param origin Source object for assigment.
+     */
     MagneticField& operator=(const MagneticField& origin)
     {
         data_.timestamp_ = origin.data_.timestamp_;
@@ -83,11 +99,17 @@ class MagneticField : public QObject
         data_.z_ = origin.data_.z_;
         data_.rx_ = origin.data_.rx_;
         data_.ry_ = origin.data_.ry_;
-        data_.rz_ = origin.data_.rz_; 
+        data_.rz_ = origin.data_.rz_;
 
         return *this;
     }
 
+    /**
+     * Comparison operator.
+     *
+     * @param right Object to compare to.
+     * @return comparison result.
+     */
     bool operator==(const MagneticField& right) const
     {
         CalibratedMagneticFieldData rdata = right.data();
@@ -101,7 +123,7 @@ class MagneticField : public QObject
                 data_.timestamp_ == rdata.timestamp_);
     }
 
-     /**
+    /**
      * Returns the value for X.
      * @return x value.
      */
@@ -144,34 +166,44 @@ class MagneticField : public QObject
     int level() const { return data_.level_; }
 
     /**
-     * Returns the timestamp.
+     * Returns the timestamp of sample as monotonic time (microsec).
      * @return timestamp value.
      */
-    quint64 timestamp() const { return data_.timestamp_; }
+    const quint64& timestamp() const { return data_.timestamp_; }
 
 private:
-    CalibratedMagneticFieldData data_;
+    CalibratedMagneticFieldData data_; /**< Contained data */
 
-    friend QDBusArgument &operator<<(QDBusArgument &argument, const MagneticField& data);
     friend const QDBusArgument &operator>>(const QDBusArgument &argument, MagneticField& data);
 };
 
 Q_DECLARE_METATYPE( MagneticField )
 
-
-inline
-QDBusArgument &operator<<(QDBusArgument &argument, const MagneticField &data)
+/**
+ * Marshall the MagneticField data into a D-Bus argument
+ *
+ * @param argument dbus argument.
+ * @param data data to marshall.
+ * @return dbus argument.
+ */
+inline QDBusArgument &operator<<(QDBusArgument &argument, const MagneticField &data)
 {
     argument.beginStructure();
-    argument << data.data_.timestamp_ << data.data_.level_;
-    argument << data.data_.x_ << data.data_.y_ << data.data_.z_;
-    argument << data.data_.rx_ << data.data_.ry_ << data.data_.rz_;
+    argument << data.data().timestamp_ << data.data().level_;
+    argument << data.data().x_ << data.data().y_ << data.data().z_;
+    argument << data.data().rx_ << data.data().ry_ << data.data().rz_;
     argument.endStructure();
     return argument;
 }
 
-inline
-const QDBusArgument &operator>>(const QDBusArgument &argument, MagneticField &data)
+/**
+ * Unmarshall MagneticField data from the D-Bus argument
+ *
+ * @param argument dbus argument.
+ * @param data unmarshalled data.
+ * @return dbus argument.
+ */
+inline const QDBusArgument &operator>>(const QDBusArgument &argument, MagneticField &data)
 {
     argument.beginStructure();
     argument >> data.data_.timestamp_ >> data.data_.level_;