Doc: Add doc to QML types in Qt Gamepad module

Task-number: QTBUG-70270
Change-Id: I6acccf981da23bae9ec83a8d2b5b17b6c2449061
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

3 files changed, 269 insertions, 34 deletions

diff --git a/src/gamepad/doc/src/qtgamepad-qmltypes.qdoc b/src/gamepad/doc/src/qtgamepad-qmltypes.qdoc
index 86d2f24..c136864 100644
--- a/src/gamepad/doc/src/qtgamepad-qmltypes.qdoc
+++ b/src/gamepad/doc/src/qtgamepad-qmltypes.qdoc
@@ -26,7 +26,7 @@
 ****************************************************************************/
 
 /*!
-  \qmlmodule QtGamepad 1.0
+  \qmlmodule QtGamepad 1.\QtMinorVersion
   \title Qt Gamepad QML Types
   \ingroup qmlmodules
   \brief Provides QML types for using gamepad hardware.
@@ -37,9 +37,9 @@
   The QML types can be imported into your application using the following
   import statement:
 
-  \code
-  import QtGamepad 1.0
-  \endcode
+  \qml \QtMinorVersion
+  import QtGamepad 1.\1
+  \endqml
 
   To link against the module, add this line to your \l qmake \c .pro file:
 
diff --git a/src/gamepad/qgamepad.cpp b/src/gamepad/qgamepad.cpp
index 4b9e25e..63e9850 100644
--- a/src/gamepad/qgamepad.cpp
+++ b/src/gamepad/qgamepad.cpp
@@ -375,6 +375,16 @@ void QGamepadPrivate::_q_handleGamepadButtonReleaseEvent(int id, QGamepadManager
  */
 
 /*!
+ *  \qmltype Gamepad
+ *  \inqmlmodule QtGamepad
+ *  \brief A gamepad device connected to a system.
+ *  \instantiates QGamepad
+ *
+ *  Gamepad QML type is used to access the current state of gamepad
+ *  hardware connected to a system
+ */
+
+/*!
  * Constructs a QGamepad with the given \a deviceId and \a parent.
  */
 QGamepad::QGamepad(int deviceId, QObject *parent)
@@ -393,9 +403,6 @@ QGamepad::QGamepad(int deviceId, QObject *parent)
     d->setName(d->gamepadManager->gamepadName(deviceId));
 }
 
-/*!
- * \brief Destroys the QGamepad.
- */
 QGamepad::~QGamepad()
 {
 }
@@ -403,11 +410,19 @@ QGamepad::~QGamepad()
 /*!
  * \property QGamepad::deviceId
  *
- * This property holds the deviceId of the gamepad device.  Multiple gamepad devices can be
+ * 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()
  */
+/*!
+ * \qmlproperty int Gamepad::deviceId
+ *
+ * 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 GamepadManager::connectedGamepads()
+ */
 int QGamepad::deviceId() const
 {
     Q_D(const QGamepad);
@@ -416,7 +431,16 @@ int QGamepad::deviceId() const
 
 /*!
  * \property QGamepad::connected
- * This read-only property holds the connectivity state of the gamepad device.
+ * \readonly
+ *
+ * The connectivity state of the gamepad device.
+ * If a gamepad is connected, this property will be true, otherwise false.
+ */
+/*!
+ * \qmlproperty bool Gamepad::connected
+ * \readonly
+ *
+ * The connectivity state of the gamepad device.
  * If a gamepad is connected, this property will be true, otherwise false.
  */
 bool QGamepad::isConnected() const
@@ -427,9 +451,15 @@ bool QGamepad::isConnected() const
 
 /*!
  * \property QGamepad::name
+ * \readonly
+ *
+ * The reported name of the gamepad if one is available.
+ */
+/*!
+ * \qmlproperty string Gamepad::name
+ * \readonly
  *
- * This read-only property holds the reported name of the gamepad if one
- * is available.
+ * The reported name of the gamepad if one is available.
  */
 QString QGamepad::name() const
 {
@@ -439,8 +469,16 @@ QString QGamepad::name() const
 
 /*!
  * \property QGamepad::axisLeftX
+ * \readonly
+ *
+ * The value of the left thumbstick's X axis.
+ * The axis values range from -1.0 to 1.0.
+ */
+/*!
+ * \qmlproperty double Gamepad::axisLeftX
+ * \readonly
  *
- * This read-only property holds the value of the left thumbstick's X axis.
+ * The value of the left thumbstick's X axis.
  * The axis values range from -1.0 to 1.0.
  */
 double QGamepad::axisLeftX() const
@@ -451,8 +489,16 @@ double QGamepad::axisLeftX() const
 
 /*!
  * \property QGamepad::axisLeftY
+ * \readonly
  *
- * This read-only property holds the value of the left thumbstick's Y axis.
+ * The value of the left thumbstick's Y axis.
+ * The axis values range from -1.0 to 1.0.
+ */
+/*!
+ * \qmlproperty double Gamepad::axisLeftY
+ * \readonly
+ *
+ * The value of the left thumbstick's Y axis.
  * The axis values range from -1.0 to 1.0.
  */
 double QGamepad::axisLeftY() const
@@ -463,8 +509,16 @@ double QGamepad::axisLeftY() const
 
 /*!
  * \property QGamepad::axisRightX
+ * \readonly
+ *
+ * This value of the right thumbstick's X axis.
+ * The axis values range from -1.0 to 1.0.
+ */
+/*!
+ * \qmlproperty double Gamepad::axisRightX
+ * \readonly
  *
- * This read-only property holds the value of the right thumbstick's X axis.
+ * This value of the right thumbstick's X axis.
  * The axis values range from -1.0 to 1.0.
  */
 double QGamepad::axisRightX() const
@@ -475,8 +529,16 @@ double QGamepad::axisRightX() const
 
 /*!
  * \property QGamepad::axisRightY
+ * \readonly
+ *
+ * This value of the right thumbstick's Y axis.
+ * The axis values range from -1.0 to 1.0.
+ */
+/*!
+ * \qmlproperty double Gamepad::axisRightY
+ * \readonly
  *
- * This read-only property holds the value of the right thumbstick's Y axis.
+ * This value of the right thumbstick's Y axis.
  * The axis values range from -1.0 to 1.0.
  */
 double QGamepad::axisRightY() const
@@ -487,8 +549,16 @@ double QGamepad::axisRightY() const
 
 /*!
  * \property QGamepad::buttonA
+ * \readonly
  *
- * This read-only property holds the state of the A button.
+ * The state of the A button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonA
+ * \readonly
+ *
+ * The state of the A button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonA() const
@@ -499,12 +569,22 @@ bool QGamepad::buttonA() const
 
 /*!
  * \property QGamepad::buttonB
+ * \readonly
  *
- * This read-only property holds the state of the B button.
+ * The state of the B button.
  * The value is \c true when pressed, and \c false when not pressed.
  *
  * \sa QGamepadManager::connectedGamepads()
  */
+/*!
+ * \qmlproperty bool Gamepad::buttonB
+ * \readonly
+ *
+ * The state of the B button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ *
+ * \sa GamepadManager::connectedGamepads()
+ */
 bool QGamepad::buttonB() const
 {
     Q_D(const QGamepad);
@@ -513,8 +593,16 @@ bool QGamepad::buttonB() const
 
 /*!
  * \property QGamepad::buttonX
+ * \readonly
  *
- * This read-only property holds the state of the X button.
+ * The state of the X button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonX
+ * \readonly
+ *
+ * The state of the X button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonX() const
@@ -525,8 +613,16 @@ bool QGamepad::buttonX() const
 
 /*!
  * \property QGamepad::buttonY
+ * \readonly
+ *
+ * The state of the Y button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonY
+ * \readonly
  *
- * This read-only property holds the state of the Y button.
+ * The state of the Y button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonY() const
@@ -537,8 +633,16 @@ bool QGamepad::buttonY() const
 
 /*!
  * \property QGamepad::buttonL1
+ * \readonly
  *
- * This read-only property holds the state of the left shoulder button.
+ * The state of the left shoulder button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonL1
+ * \readonly
+ *
+ * The state of the left shoulder button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonL1() const
@@ -549,8 +653,16 @@ bool QGamepad::buttonL1() const
 
 /*!
  * \property QGamepad::buttonR1
+ * \readonly
  *
- * This read-only property holds the state of the right shoulder button.
+ * The state of the right shoulder button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonR1
+ * \readonly
+ *
+ * The state of the right shoulder button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonR1() const
@@ -561,8 +673,17 @@ bool QGamepad::buttonR1() const
 
 /*!
  * \property QGamepad::buttonL2
+ * \readonly
+ *
+ * The value of the left trigger button.
+ * This trigger value ranges from 0.0 when not pressed to 1.0
+ * when pressed completely.
+ */
+/*!
+ * \qmlproperty double Gamepad::buttonL2
+ * \readonly
  *
- * This read-only property holds the value of the left trigger button.
+ * The value of the left trigger button.
  * This trigger value ranges from 0.0 when not pressed to 1.0
  * when pressed completely.
  */
@@ -574,8 +695,17 @@ double QGamepad::buttonL2() const
 
 /*!
  * \property QGamepad::buttonR2
+ * \readonly
  *
- * This read-only property holds the value of the right trigger button.
+ * The value of the right trigger button.
+ * This trigger value ranges from 0.0 when not pressed to 1.0
+ * when pressed completely.
+ */
+/*!
+ * \qmlproperty double Gamepad::buttonR2
+ * \readonly
+ *
+ * The value of the right trigger button.
  * This trigger value ranges from 0.0 when not pressed to 1.0
  * when pressed completely.
  */
@@ -587,8 +717,17 @@ double QGamepad::buttonR2() const
 
 /*!
  * \property QGamepad::buttonSelect
+ * \readonly
  *
- * This read-only property holds the state of the Select button.
+ * The state of the Select button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ * This button can sometimes be labeled as the Back button on some gamepads.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonSelect
+ * \readonly
+ *
+ * The state of the Select button.
  * The value is \c true when pressed, and \c false when not pressed.
  * This button can sometimes be labeled as the Back button on some gamepads.
  */
@@ -600,8 +739,17 @@ bool QGamepad::buttonSelect() const
 
 /*!
  * \property QGamepad::buttonStart
+ * \readonly
+ *
+ * The state of the Start button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ * This button can sometimes be labeled as the Forward button on some gamepads.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonStart
+ * \readonly
  *
- * This read-only property holds the state of the Start button.
+ * The state of the Start button.
  * The value is \c true when pressed, and \c false when not pressed.
  * This button can sometimes be labeled as the Forward button on some gamepads.
  */
@@ -613,8 +761,17 @@ bool QGamepad::buttonStart() const
 
 /*!
  * \property QGamepad::buttonL3
+ * \readonly
  *
- * This read-only property holds the state of the left stick button.
+ * The state of the left stick button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ * This button is usually triggered by pressing the left joystick itself.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonL3
+ * \readonly
+ *
+ * The state of the left stick button.
  * The value is \c true when pressed, and \c false when not pressed.
  * This button is usually triggered by pressing the left joystick itself.
  */
@@ -626,8 +783,17 @@ bool QGamepad::buttonL3() const
 
 /*!
  * \property QGamepad::buttonR3
+ * \readonly
  *
- * This read-only property holds the state of the right stick button.
+ * The state of the right stick button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ * This button is usually triggered by pressing the right joystick itself.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonR3
+ * \readonly
+ *
+ * The state of the right stick button.
  * The value is \c true when pressed, and \c false when not pressed.
  * This button is usually triggered by pressing the right joystick itself.
  */
@@ -639,8 +805,16 @@ bool QGamepad::buttonR3() const
 
 /*!
  * \property QGamepad::buttonUp
+ * \readonly
+ *
+ * The state of the direction pad up button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonUp
+ * \readonly
  *
- * This read-only property holds the state of the direction pad up button.
+ * The state of the direction pad up button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonUp() const
@@ -651,8 +825,16 @@ bool QGamepad::buttonUp() const
 
 /*!
  * \property QGamepad::buttonDown
+ * \readonly
  *
- * This read-only property holds the state of the direction pad down button.
+ * The of the direction pad down button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonDown
+ * \readonly
+ *
+ * The of the direction pad down button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonDown() const
@@ -663,8 +845,16 @@ bool QGamepad::buttonDown() const
 
 /*!
  * \property QGamepad::buttonLeft
+ * \readonly
+ *
+ * The state of the direction pad left button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonLeft
+ * \readonly
  *
- * This read-only property holds the state of the direction pad left button.
+ * The state of the direction pad left button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonLeft() const
@@ -675,8 +865,16 @@ bool QGamepad::buttonLeft() const
 
 /*!
  * \property QGamepad::buttonRight
+ * \readonly
  *
- * This read-only property holds the state of the direction pad right button.
+ * The state of the direction pad right button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*!
+ * \qmlproperty bool Gamepad::buttonRight
+ * \readonly
+ *
+ * The state of the direction pad right button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonRight() const
@@ -687,8 +885,15 @@ bool QGamepad::buttonRight() const
 
 /*!
  * \property QGamepad::buttonCenter
+ * \readonly
+ *
+ * The state of the center button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ */
+/*
+ * \qmlproperty bool Gamepad::buttonCenter
  *
- * This read-only property holds the state of the center button.
+ * The state of the center button.
  * The value is \c true when pressed, and \c false when not pressed.
  */
 bool QGamepad::buttonCenter() const
@@ -699,12 +904,23 @@ bool QGamepad::buttonCenter() const
 
 /*!
  * \property QGamepad::buttonGuide
+ * \readonly
  *
- * This read-only property holds the state of the guide button.
+ * The state of the guide button.
  * The value is \c true when pressed, and \c false when not pressed.
  * This button is typically the one in the center of the gamepad with a logo.
  * Some gamepads will not have a guide button.
  */
+/*
+ * \qmlproperty bool Gamepad::buttonGuide
+ * \readonly
+ *
+ * The state of the guide button.
+ * The value is \c true when pressed, and \c false when not pressed.
+ * This button is typically the one in the center of the gamepad with a logo.
+ * Some gamepads will not have a guide button.
+ */
+
 bool QGamepad::buttonGuide() const
 {
     Q_D(const QGamepad);
diff --git a/src/gamepad/qgamepadmanager.cpp b/src/gamepad/qgamepadmanager.cpp
index 4c86e62..c8a0eb5 100644
--- a/src/gamepad/qgamepadmanager.cpp
+++ b/src/gamepad/qgamepadmanager.cpp
@@ -144,6 +144,17 @@ void QGamepadManagerPrivate::loadBackend()
  */
 
 /*!
+ * \qmltype GamepadManager
+ * \inqmlmodule QtGamepad
+ * \instantiates QGamepadManager
+ * \brief Queries attached gamepads and related events.
+ *
+ * GamepadManager QML type provides a high-level interface for
+ * querying the attached gamepads and events related to all of the
+ * connected devices.
+ */
+
+/*!
  * Constructor for QGamepadManager.
  */
 
@@ -213,7 +224,15 @@ QString QGamepadManager::gamepadName(int deviceId) const
 }
 
 /*!
-    Returns a QList containing the \l {QGamepad::}{deviceId}
+   \qmlproperty var GamepadManager::connectedGamepads
+   \readonly
+
+    Returns a list of integers containing the \l {QGamepad::}{deviceId}
+    values of the connected gamepads.
+*/
+
+/*!
+    Returns a list of integers containing the \l {QGamepad::}{deviceId}
     values of the connected gamepads.
 */
 const QList<int> QGamepadManager::connectedGamepads() const