doc: Reduce expectations for QInputDevice::devices()

I was hoping we could get the list mostly correct and complete on most
platforms; but in practice, it's proving difficult on most platforms.
Hopefully we can find ways to improve it over time.

Task-number: QTBUG-101648
Task-number: QTBUG-101875
Task-number: QTBUG-112432
Task-number: QTBUG-113706
Task-number: QTBUG-113711
Change-Id: I16b6900cddb54197fb7b833a513e36996de72d51
Pick-to: 6.2 6.5
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
Reviewed-by: Morten Johan Sørvig <morten.sorvig@qt.io>

1 files changed, 7 insertions, 0 deletions

diff --git a/src/gui/kernel/qinputdevice.cpp b/src/gui/kernel/qinputdevice.cpp
index 8a4066c0a3..f20351a562 100644
--- a/src/gui/kernel/qinputdevice.cpp
+++ b/src/gui/kernel/qinputdevice.cpp
@@ -235,6 +235,13 @@ Q_CONSTINIT static QBasicMutex devicesMutex;
 /*!
     Returns a list of all registered input devices (keyboards and pointing devices).
 
+    \note The list of devices is not always complete on all platforms. So far,
+    the most-complete information is available on the \l {Qt for Linux/X11}{X11}
+    platform, at startup and in response to hot-plugging. Most other platforms
+    are only able to provide generic devices of various types, only after receiving
+    events from them; and most platforms do not tell Qt when a device is plugged in,
+    or when it is unplugged at runtime.
+
     \note The returned list cannot be used to add new devices. To add a simulated
     touch screen for an autotest, QTest::createTouchDevice() can be used.
     Platform plugins should call QWindowSystemInterface::registerInputDevice()