6 files changed, 147 insertions, 19 deletions
diff --git a/examples/gamepad/quickGamepad/qml/ButtonImage.qml b/examples/gamepad/quickGamepad/qml/ButtonImage.qml
index 8057542..2547545 100644
--- a/examples/gamepad/quickGamepad/qml/ButtonImage.qml
+++ b/examples/gamepad/quickGamepad/qml/ButtonImage.qml
@@ -39,7 +39,7 @@
 ****************************************************************************/
 
 import QtQuick 2.0
-import QtGraphicalEffects 1.0
+//import QtGraphicalEffects 1.0
 
 Item {
     width: buttonImage.sourceSize.width
diff --git a/examples/gamepad/quickGamepad/qml/DPad.qml b/examples/gamepad/quickGamepad/qml/DPad.qml
index d34c953..0f7a1ad 100644
--- a/examples/gamepad/quickGamepad/qml/DPad.qml
+++ b/examples/gamepad/quickGamepad/qml/DPad.qml
@@ -40,7 +40,6 @@
 
 import QtQuick 2.0
 import QtGamepad 1.0
-import QtGraphicalEffects 1.0
 
 Item {
     property Gamepad gamepad
diff --git a/src/gamepad/doc/src/qtgamepad-index.qdoc b/src/gamepad/doc/src/qtgamepad-index.qdoc
index 5fcd7b0..8b4aa25 100644
--- a/src/gamepad/doc/src/qtgamepad-index.qdoc
+++ b/src/gamepad/doc/src/qtgamepad-index.qdoc
@@ -30,18 +30,48 @@
   \title Qt Gamepad
   \brief A cross-platform library to facilitate the use of gamepad hardware in Qt and Qt Quick applications.
 
-  Qt Gamepad is an add-on library that enables Qt applications to support
-  the use of gamepad hardware. The module provides both QML and C++ interfaces.
+  Qt Gamepad is an add-on library that enables Qt applications to support the
+  use of gamepad hardware and in some cases remote control equipment.  The
+  module provides both QML and C++ interfaces. The primary target audience are
+  embedded devices with fullscreen user interfaces, and mobile applications
+  targeting TV-like form factors.
+
+  The currently supported platforms are:
+
+  \list
+  \li Windows (Win32 desktop, via XInput 1.3 & 1.4)
+  \li Linux (evdev)
+  \li Linux (SDL2)
+  \li Android
+  \li macOS, iOS, tvOS (including the tvOS remote)
+  \endlist
+
+  This module provides classes that can:
+
+  \list
+  \li Read input events from game controllers (Button and Axis events),
+  \li expose these events both to C++ and Qt Quick (QML),
+  \li provide basic gamepad layout configurability, and
+  \li provide optional key and mouse event generation upon gamepad button presses.
+  \endlist
+
+  \note The API is designed with XBox and similar controllers in mind. Joysticks
+  are not in scope for this module. A number of third-party gamepads may be
+  supported as well, however, some of these may need custom configuration steps
+  in order to map the button/trigger codes the device or driver in question
+  provides onto what QtGamepad expects. The can be done by the
+  \l{Qt Gamepad Configure Buttons Example}{configureButtons} example that can also
+  save the generated layout persistently for use by other applications.
 
   \section1 Getting Started
 
   Before you start using the APIs provided by this module, ensure that the
   gamepad is detected by your development environment.
 
-  \section2 Linux/X11
+  \section2 Linux
 
   On standard Linux distributions such as Ubuntu, gamepads such as XBox or
-  PlayStaion controllers are detected out-of-the-box. To check if the
+  PlayStation controllers are detected out-of-the-box. To check if the
   gamepad is detected, \c grep the \c dmesg logs using:
 
   \badcode
@@ -52,6 +82,52 @@
   the \c joystick package is installed. If not, install the package and \c grep
   the \c dmesg logs again.
 
+  It is strongly recommended to verify that the gamepad's input device is
+  present, and is sending events, via the \c lsinput and \c evtest utilities.
+
+  PlayStation controllers will likely need the help of an additional tool like
+  \l{xboxdrv}{https://github.com/xboxdrv/xboxdrv}. Once installed, and having a
+  PS3 controller connected via USB, the following will ensure correct operation
+  with QtGamepad:
+
+  \badcode
+  sudo xboxdrv --detach-kernel-driver --mimic-xpad -s
+  \endcode
+
+  Qt Gamepad uses a plugin-based, multi-backend architecture. This means that on
+  some platforms, like Linux, there are multiple backends available. In case of
+  Linux, the choices are:
+
+  \list
+
+  \li \c evdev - a backend reading events directly from the evdev input device
+
+  \li \c sdl2 - a backend using the Gamepad module of SDL2. This plugin is only
+  built when SDL2 is present at build time, and therefore will typically be
+  missing from the pre-built Qt packages. This backend likely has broader
+  support for various hardware, at the expense of an additional third-party
+  dependency.
+
+  \endlist
+
+  To force a given backend, set the \c QT_GAMEPAD environment variable to the
+  name of the desired backend.
+
+  The availability of gamepad devices is monitored via \c libudev, assuming Qt
+  was built with libudev support enabled. This means that connecting wired
+  gamepads or wireless dongles is possible also while an application is
+  running.
+
+  \note wireless dongles may report one or more input devices even when no
+  actual controllers have been connected to them. Qt Gamepad will interpret this
+  as having connected gamepads present.
+
+  With the \c evdev backend, to explicitly specify the input device to use, set
+  the environment variable \c{QT_GAMEPAD_DEVICE} to the desired
+  /dev/input/event* node. This should not be needed normally, but can be useful
+  in case multiple gamepads are connected and only one of them is interesting to
+  the application.
+
   \section2 Windows
 
   The Windows Plug-n-Play service automatically installs the necessary drivers
@@ -62,7 +138,30 @@
   To test whether gamepad input is detected, select
   \uicontrol {Gamepad Controller Settings} from the context menu, select
   \uicontrol {Properties > Test}, and start testing. You can also run the
-  \l{Qt Gamepad Configure Buttons Example}{configureButtons} example to test.
+  \l{Qt Gamepad Qt Quick Example}{quickGamepad} example to test.
+
+  \section2 Android
+
+  The Android backend uses the \c InputDevice API.
+
+  \section2 macOS, iOS, tvOS
+
+  This backend uses the \c GCController API.
+
+  Besides game controllers, it also supports the tvOS remote (microGamepad). The
+  mapping for this is the following:
+
+  \list
+  \li \c{X button} - play/pause
+  \li \c{A button} - pressing the touch area
+  \li \c{left thumbstick} - the touch area
+  \endlist
+
+  \section2 Troubleshooting
+
+  Some backends (\c evdev on Linux and \c xinput on Windows) and the plugin
+  loader utilize the logging category \c{qt.gamepad}. Enabling this will print
+  useful information on the debug output.
 
   \section1 Examples
 
diff --git a/src/gamepad/qgamepad.cpp b/src/gamepad/qgamepad.cpp
index 9c10267..399e801 100644
--- a/src/gamepad/qgamepad.cpp
+++ b/src/gamepad/qgamepad.cpp
@@ -355,9 +355,7 @@ void QGamepadPrivate::_q_handleGamepadButtonReleaseEvent(int id, QGamepadManager
  */
 
 /*!
- * \brief Constructs a QGamepad for \a deviceId.
- * \param deviceId is the id of the gamepad you wish to see the state of
- * \param parent
+ * Constructs a QGamepad with the given \a deviceId and \a parent.
  */
 QGamepad::QGamepad(int deviceId, QObject *parent)
     : QObject(*new QGamepadPrivate(deviceId), parent)
@@ -383,10 +381,10 @@ QGamepad::~QGamepad()
 /*!
  * \property QGamepad::deviceId
  *
- * This property holds the deviceId of the gamepad device.  It is possible for there to be
- * multiple gamepad devices connected at any given time, so setting this property defines
- * which gamepad to use.
+ * This property holds the deviceId of the gamepad device.  Multiple gamepad devices can be
+ * connected at any given time, so setting this property defines which gamepad to use.
  *
+ * \sa QGamepadManager::connectedGamepads()
  */
 int QGamepad::deviceId() const
 {
@@ -420,7 +418,7 @@ QString QGamepad::name() const
  * \property QGamepad::axisLeftX
  *
  * This property holds the value of the left thumbstick's X axis.
- * The range of axis values are from -1.0 to 1.0
+ * The range of axis values are from -1.0 to 1.0.
  */
 double QGamepad::axisLeftX() const
 {
@@ -432,7 +430,7 @@ double QGamepad::axisLeftX() const
  * \property QGamepad::axisLeftY
  *
  * This property holds the value of the left thumbstick's Y axis.
- * The range of axis values are from -1.0 to 1.0
+ * The range of axis values are from -1.0 to 1.0.
  */
 double QGamepad::axisLeftY() const
 {
@@ -444,7 +442,7 @@ double QGamepad::axisLeftY() const
  * \property QGamepad::axisRightX
  *
  * This property holds the value of the right thumbstick's X axis.
- * The range of axis values are from -1.0 to 1.0
+ * The range of axis values are from -1.0 to 1.0.
  */
 double QGamepad::axisRightX() const
 {
@@ -456,7 +454,7 @@ double QGamepad::axisRightX() const
  * \property QGamepad::axisRightY
  *
  * This property holds the value of the right thumbstick's Y axis.
- * The range of axis values are from -1.0 to 1.0
+ * The range of axis values are from -1.0 to 1.0.
  */
 double QGamepad::axisRightY() const
 {
@@ -481,6 +479,8 @@ bool QGamepad::buttonA() const
  *
  * This property holds the state of the B button.  True when pressed, false when not
  * pressed.
+ *
+ * \sa QGamepadManager::connectedGamepads()
  */
 bool QGamepad::buttonB() const
 {
@@ -566,7 +566,7 @@ double QGamepad::buttonR2() const
  * \property QGamepad::buttonSelect
  *
  * This property holds the state of the Select button.  True when pressed, false when not
- * pressed. This button can sometimes be labled as the Back button on some gamepads.
+ * pressed. This button can sometimes be labeled as the Back button on some gamepads.
  */
 bool QGamepad::buttonSelect() const
 {
@@ -578,7 +578,7 @@ bool QGamepad::buttonSelect() const
  * \property QGamepad::buttonStart
  *
  * This property holds the state of the Start button.  True when pressed, false when not
- * pressed. This button can sometimes be labled as the Forward button on some gamepads.
+ * pressed. This button can sometimes be labeled as the Forward button on some gamepads.
  */
 bool QGamepad::buttonStart() const
 {
diff --git a/src/gamepad/qgamepadkeynavigation.cpp b/src/gamepad/qgamepadkeynavigation.cpp
index 2eac092..686e8bd 100644
--- a/src/gamepad/qgamepadkeynavigation.cpp
+++ b/src/gamepad/qgamepadkeynavigation.cpp
@@ -118,6 +118,19 @@ void QGamepadKeyNavigationPrivate::_q_processGamepadButtonReleaseEvent(int index
     sendGeneratedKeyEvent(event);
 }
 
+/*!
+   \class QGamepadKeyNavigation
+   \inmodule QtGamepad
+   \brief Provides support for keyboard events triggered by gamepads.
+
+   QGamepadKeyNavigation provides support for keyboard events triggered by
+   gamepads.
+ */
+
+/*!
+ * Constructs a QGamepadNavigation object with the given \a parent.
+ */
+
 QGamepadKeyNavigation::QGamepadKeyNavigation(QObject *parent)
     : QObject(*new QGamepadKeyNavigationPrivate(), parent)
 {
diff --git a/src/gamepad/qgamepadmanager.cpp b/src/gamepad/qgamepadmanager.cpp
index 4d5c596..9628f0e 100644
--- a/src/gamepad/qgamepadmanager.cpp
+++ b/src/gamepad/qgamepadmanager.cpp
@@ -126,6 +126,19 @@ void QGamepadManagerPrivate::loadBackend()
     }
 }
 
+/*!
+   \class QGamepadManager
+   \inmodule QtGamepad
+   \brief Queries attached gamepads and related events.
+
+   QGamepadManager provides a high-level interface for querying the attached
+   gamepads and events related to all of the connected devices.
+ */
+
+/*!
+ * Constructor for QGamepadManager.
+ */
+
 QGamepadManager::QGamepadManager() :
     QObject(*new QGamepadManagerPrivate(), nullptr)
 {
@@ -148,6 +161,10 @@ QGamepadManager::QGamepadManager() :
         qCWarning(gp) << "Failed to start gamepad backend";
 }
 
+/*!
+ * Destructor for QGamepadManager.
+ */
+
 QGamepadManager::~QGamepadManager()
 {
     Q_D(QGamepadManager);