Document that the QSensor constructor should not be used directly

Change-Id: I1907497b2bb3b1be65e98223e0337eef358743b6
Reviewed-by: Lorn Potter <lorn.potter@jollamobile.com>

1 files changed, 17 insertions, 0 deletions

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)