From ceec1eda82dd9b6f8823bb7f9639e6f79763331e Mon Sep 17 00:00:00 2001
From: Thomas McGuire <thomas.mcguire.qnx@kdab.com>
Date: Mon, 6 May 2013 11:27:43 +0200
Subject: Document that the QSensor constructor should not be used directly

Change-Id: I1907497b2bb3b1be65e98223e0337eef358743b6
Reviewed-by: Lorn Potter <lorn.potter@jollamobile.com>
---
 src/sensors/doc/snippets/sensors/creating.cpp | 16 ++++++++++++++++
 src/sensors/qsensor.cpp                       | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/src/sensors/doc/snippets/sensors/creating.cpp b/src/sensors/doc/snippets/sensors/creating.cpp
index 01e3e36..7988f7e 100644
--- a/src/sensors/doc/snippets/sensors/creating.cpp
+++ b/src/sensors/doc/snippets/sensors/creating.cpp
@@ -40,6 +40,7 @@
 
 #include <QObject>
 #include <qaccelerometer.h>
+#include <qmagnetometer.h>
 #include <qorientationsensor.h>
 
 class MyObject : public QObject
@@ -59,5 +60,20 @@ QOrientationSensor orient_sensor;
 
     Q_UNUSED(sensor)
     Q_UNUSED(orient_sensor);
+
+{
+//! [2]
+QMagnetometer *magnetometer = new QMagnetometer(this);
+//! [2]
+Q_UNUSED(magnetometer);
+}
+
+{
+//! [3]
+QSensor *magnetometer = new QSensor(QMagnetometer::type, this);
+//! [3]
+Q_UNUSED(magnetometer);
+}
+
 }
 
diff --git a/src/sensors/qsensor.cpp b/src/sensors/qsensor.cpp
index c725677..473c459 100644
--- a/src/sensors/qsensor.cpp
+++ b/src/sensors/qsensor.cpp
@@ -258,6 +258,23 @@ void QSensorPrivate::init(const QByteArray &sensorType)
 
 /*!
     Construct the \a type sensor as a child of \a parent.
+
+    Do not use this constructor if a derived class exists for the specific sensor type.
+
+    The wrong way is to use the base class constructor:
+    \snippet sensors/creating.cpp 3
+    The right way is to create an instance of the derived class:
+    \snippet sensors/creating.cpp 2
+
+    The derived classes have
+    additional properties and data members which are needed for certain features such as
+    geo value support in QMagnetometer or acceleration mode support in QAccelerometer.
+    These features will only work properly when creating a sensor instance from a QSensor
+    subclass.
+
+    Only use this constructor if there is no derived sensor class available. Note that all
+    built-in sensors have a derived class, so using this constructor should only be necessary
+    when implementing custom sensors, like in the \l {Qt Sensors - Grue Sensor Example}{Grue sensor example}.
 */
 QSensor::QSensor(const QByteArray &type, QObject *parent)
     : QObject(*new QSensorPrivate, parent)
-- 
cgit v1.2.1