Document that the QSensor constructor should not be used directly

This is a backport of QtSensors commit
ceec1eda82dd9b6f8823bb7f9639e6f79763331e

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

2 files changed, 34 insertions, 0 deletions

diff --git a/doc/src/snippets/sensors/creating.cpp b/doc/src/snippets/sensors/creating.cpp
index 9852c05ef1..806acc05f4 100644
--- a/doc/src/snippets/sensors/creating.cpp
+++ b/doc/src/snippets/sensors/creating.cpp
@@ -62,5 +62,19 @@ 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 fdbe9d4f61..54d91b79f5 100644
--- a/src/sensors/qsensor.cpp
+++ b/src/sensors/qsensor.cpp
@@ -201,8 +201,28 @@ void QSensorPrivate::init(const QByteArray &sensorType)
     type = sensorType;
     q->registerInstance(); // so the availableSensorsChanged() signal works
 }
+
 /*!
     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 snippets/sensors/creating.cpp 3
+    The right way is to create an instance of the derived class:
+    \snippet snippets/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 {Grue Application}{Grue sensor
+    example}.
+
     \since 1.0
 */
 QSensor::QSensor(const QByteArray &type, QObject *parent)