Doc: Fix documentation warnings

Add missing function and function/qml method parameter documentation,
linking issues, and other minor tweaks.

QDoc fails to parse a Q_PROPERTY if the property type includes the
keyword 'enum' - fix that in the header file for
QWaylandXdgToplevel::DecorationMode.

These changes bring the currect warning count to zero.

Fixes: QTBUG-79817
Change-Id: I302b110eb91858f06e9cd410872a12365d421a8e
Reviewed-by: Paul Wicking <paul.wicking@qt.io>

11 files changed, 89 insertions, 24 deletions

diff --git a/src/compositor/compositor_api/qwaylandcompositor.cpp b/src/compositor/compositor_api/qwaylandcompositor.cpp
index 08c0ef51c..5b77a3be1 100644
--- a/src/compositor/compositor_api/qwaylandcompositor.cpp
+++ b/src/compositor/compositor_api/qwaylandcompositor.cpp
@@ -489,33 +489,35 @@ void QWaylandCompositorPrivate::loadServerBufferIntegration()
 /*!
   \qmlsignal void QtWaylandCompositor::WaylandCompositor::surfaceRequested(WaylandClient client, int id, int version)
 
-  This signal is emitted when a client has created a surface.
-  The slot connecting to this signal may create and initialize
-  a WaylandSurface instance in the scope of the slot.
-  Otherwise a default surface is created.
+  This signal is emitted when a \a client has created a surface with id \a id.
+  The interface \a version is also available.
+
+  The slot connecting to this signal may create and initialize a WaylandSurface
+  instance in the scope of the slot. Otherwise a default surface is created.
 */
 
 /*!
   \fn void QWaylandCompositor::surfaceRequested(QWaylandClient *client, uint id, int version)
 
-  This signal is emitted when a client has created a surface.
-  The slot connecting to this signal may create and initialize
-  a QWaylandSurface instance in the scope of the slot.
-  Otherwise a default surface is created.
+  This signal is emitted when a \a client has created a surface with id \a id.
+  The interface \a version is also available.
+
+  The slot connecting to this signal may create and initialize a QWaylandSurface
+  instance in the scope of the slot. Otherwise a default surface is created.
 
   Connections to this signal must be of Qt::DirectConnection connection type.
 */
 
 /*!
-  \qmlsignal void QtWaylandCompositor::WaylandCompositor::surfaceCreated(QWaylandSurface *surface)
+  \qmlsignal void QtWaylandCompositor::WaylandCompositor::surfaceCreated(WaylandSurface surface)
 
-  This signal is emitted when a new WaylandSurface instance has been created.
+  This signal is emitted when a new WaylandSurface instance \a surface has been created.
 */
 
 /*!
   \fn void QWaylandCompositor::surfaceCreated(QWaylandSurface *surface)
 
-  This signal is emitted when a new QWaylandSurface instance has been created.
+  This signal is emitted when a new QWaylandSurface instance \a surface has been created.
 */
 
 /*!
diff --git a/src/compositor/compositor_api/qwaylandquickitem.cpp b/src/compositor/compositor_api/qwaylandquickitem.cpp
index 80e84a884..6c4ca8b13 100644
--- a/src/compositor/compositor_api/qwaylandquickitem.cpp
+++ b/src/compositor/compositor_api/qwaylandquickitem.cpp
@@ -1183,9 +1183,11 @@ QVariant QWaylandQuickItem::inputMethodQuery(Qt::InputMethodQuery query, QVarian
 */
 
 /*!
-    Returns true if the item is hidden, though the texture
+    \property QWaylandQuickItem::paintEnabled
+
+    Holds \c true if the item is hidden, though the texture
     is still updated. As opposed to hiding the item by
-    setting \l{Item::visible}{visible} to \c false, setting this property to \c false
+    setting \l{QQuickItem::}{visible} to \c false, setting this property to \c false
     will not prevent mouse or keyboard input from reaching item.
 */
 bool QWaylandQuickItem::paintEnabled() const
@@ -1201,6 +1203,19 @@ void QWaylandQuickItem::setPaintEnabled(bool enabled)
     update();
 }
 
+/*!
+    \qmlproperty  bool QtWaylandCompositor::WaylandQuickItem::touchEventsEnabled
+
+    This property holds \c true if touch events are forwarded to the client
+    surface, \c false otherwise.
+*/
+
+/*!
+    \property QWaylandQuickItem::touchEventsEnabled
+
+    This property holds \c true if touch events are forwarded to the client
+    surface, \c false otherwise.
+*/
 bool QWaylandQuickItem::touchEventsEnabled() const
 {
     Q_D(const QWaylandQuickItem);
diff --git a/src/compositor/compositor_api/qwaylandseat.cpp b/src/compositor/compositor_api/qwaylandseat.cpp
index 0be10f450..83d0335c4 100644
--- a/src/compositor/compositor_api/qwaylandseat.cpp
+++ b/src/compositor/compositor_api/qwaylandseat.cpp
@@ -498,11 +498,13 @@ void QWaylandSeat::sendFullKeyEvent(QKeyEvent *event)
  * \qmlmethod void QtWaylandCompositor::WaylandSeat::sendKeyEvent(int qtKey, bool pressed)
  * \since 5.12
  *
- * Sends a key press or release to the keyboard device.
+ * Sends a key press (if \a pressed is \c true) or release (if \a pressed is \c false)
+ * event of a key \a qtKey to the keyboard device.
  */
 
 /*!
- * Sends a key press or release to the keyboard device.
+ * Sends a key press (if \a pressed is \c true) or release (if \a pressed is \c false)
+ * event of a key \a qtKey to the keyboard device.
  *
  * \since 5.12
  */
@@ -734,6 +736,10 @@ void QWaylandSeat::handleMouseFocusDestroyed()
  * This signal is emitted when the client has requested for a specific \a surface to be the mouse
  * cursor. For example, when the user hovers over a particular surface, and you want the cursor
  * to change into a resize arrow.
+ *
+ * Both \a hotspotX and \a hotspotY are offsets from the top-left of a pointer surface, where a
+ * click should happen. For example, if the requested cursor surface is an arrow, the parameters
+ * indicate where the arrow's tip is, on that surface.
  */
 
 /*!
diff --git a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
index 440a793cb..dc95dc5be 100644
--- a/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
+++ b/src/compositor/doc/src/qtwaylandcompositor-overview.qdoc
@@ -54,7 +54,7 @@
   Communication (IPC). Qt provides the APIs that can be used to develop the
   remaining parts of an application manager in other modules. The
   \l {https://www.qt.io/qt-automotive-suite/}{Qt Automotive Suite} provides
-  \l{Qt Application Manager}, which is a complete application manager that
+  \l{https://doc.qt.io/QtApplicationManager}{Qt Application Manager}, which is a complete application manager that
   includes a compositor developed using Qt Wayland Compositor.
 
   For more information on Wayland, see \l{Wayland and Qt}.
diff --git a/src/compositor/extensions/qwaylandidleinhibitv1.cpp b/src/compositor/extensions/qwaylandidleinhibitv1.cpp
index b97f58130..d034c47fb 100644
--- a/src/compositor/extensions/qwaylandidleinhibitv1.cpp
+++ b/src/compositor/extensions/qwaylandidleinhibitv1.cpp
@@ -45,7 +45,7 @@ QT_BEGIN_NAMESPACE
     \class QWaylandIdleInhibitManagerV1
     \inmodule QtWaylandCompositor
     \since 5.14
-    \brief Provides an extension that allows to inhibit the idle behavior of the compositor
+    \brief Provides an extension that allows to inhibit the idle behavior of the compositor.
     \sa QWaylandSurface::inhibitsIdle
 
     The QWaylandIdleInhibitV1 extension provides a way for a client to inhibit the idle behavior of
@@ -60,7 +60,7 @@ QT_BEGIN_NAMESPACE
     \qmltype IdleInhibitManagerV1
     \inqmlmodule QtWayland.Compositor
     \since 5.14
-    \brief Provides an extension that allows to inhibit the idle behavior of the compositor
+    \brief Provides an extension that allows to inhibit the idle behavior of the compositor.
     \sa WaylandSurface::inhibitsIdle
 
     The IdleInhibitManagerV1 extension provides a way for a client to inhibit the idle behavior of
diff --git a/src/compositor/extensions/qwaylandiviapplication.cpp b/src/compositor/extensions/qwaylandiviapplication.cpp
index d0422a052..50242ab19 100644
--- a/src/compositor/extensions/qwaylandiviapplication.cpp
+++ b/src/compositor/extensions/qwaylandiviapplication.cpp
@@ -145,7 +145,7 @@ QByteArray QWaylandIviApplication::interfaceName()
  *
  * This signal is emitted when the client has requested an \c ivi_surface to be associated
  * with \a surface, which is identified by \a iviId. The handler for this signal is
- * expected to create the ivi surface and initialize it within the scope of the
+ * expected to create the ivi surface for \a resource and initialize it within the scope of the
  * signal emission. If no ivi surface is created, a default one will be created instead.
  */
 
diff --git a/src/compositor/extensions/qwaylandquickshellintegration.cpp b/src/compositor/extensions/qwaylandquickshellintegration.cpp
index 5d3d526f1..100e4bd59 100644
--- a/src/compositor/extensions/qwaylandquickshellintegration.cpp
+++ b/src/compositor/extensions/qwaylandquickshellintegration.cpp
@@ -33,7 +33,7 @@
  * \class QWaylandQuickShellIntegration
  * \inmodule QtWaylandCompositor
  * \since 5.14
- * \brief Provides support for shell surface integration with QtQuick
+ * \brief Provides support for shell surface integration with QtQuick.
  *
  * Shell surface implementations should inherit from this class in order to provide
  * an integration between the shell surface and QtQuick.
diff --git a/src/compositor/extensions/qwaylandshellsurface.cpp b/src/compositor/extensions/qwaylandshellsurface.cpp
index 6fda778f6..74194b35e 100644
--- a/src/compositor/extensions/qwaylandshellsurface.cpp
+++ b/src/compositor/extensions/qwaylandshellsurface.cpp
@@ -64,7 +64,7 @@
  * \fn QWaylandQuickShellIntegration *QWaylandShellSurface::createIntegration(QWaylandQuickShellSurfaceItem *item)
  *
  * Creates a QWaylandQuickShellIntegration for this QWaylandQuickShellSurface. It's called
- * automatically when QWaylandQuickShellSurfaceItem::shellSurface is assigned.
+ * automatically when \a {item}'s \l {QWaylandQuickShellSurfaceItem::}{shellSurface} is assigned.
  *
  * \sa QWaylandQuickShellSurfaceItem
  */
diff --git a/src/compositor/extensions/qwaylandxdgoutputv1.cpp b/src/compositor/extensions/qwaylandxdgoutputv1.cpp
index 2ab26c162..817cb2e4a 100644
--- a/src/compositor/extensions/qwaylandxdgoutputv1.cpp
+++ b/src/compositor/extensions/qwaylandxdgoutputv1.cpp
@@ -47,7 +47,7 @@ QT_BEGIN_NAMESPACE
  * \qmltype XdgOutputManagerV1
  * \inqmlmodule QtWayland.Compositor
  * \since 5.14
- * \brief Provides an extension for describing outputs in a desktop oriented fashion
+ * \brief Provides an extension for describing outputs in a desktop oriented fashion.
  *
  * The XdgOutputManagerV1 extension provides a way for a compositor to describe outputs in a way
  * that is more in line with the concept of an output on desktop oriented systems.
@@ -104,7 +104,7 @@ QT_BEGIN_NAMESPACE
  * \class QWaylandXdgOutputManagerV1
  * \inmodule QtWaylandCompositor
  * \since 5.14
- * \brief Provides an extension for describing outputs in a desktop oriented fashion
+ * \brief Provides an extension for describing outputs in a desktop oriented fashion.
  *
  * The QWaylandXdgOutputManagerV1 extension provides a way for a compositor to describe outputs in a way
  * that is more in line with the concept of an output on desktop oriented systems.
diff --git a/src/compositor/extensions/qwaylandxdgshell.h b/src/compositor/extensions/qwaylandxdgshell.h
index 2e3e28180..c79b22350 100644
--- a/src/compositor/extensions/qwaylandxdgshell.h
+++ b/src/compositor/extensions/qwaylandxdgshell.h
@@ -153,7 +153,12 @@ class Q_WAYLAND_COMPOSITOR_EXPORT QWaylandXdgToplevel : public QObject
     Q_PROPERTY(bool fullscreen READ fullscreen NOTIFY fullscreenChanged)
     Q_PROPERTY(bool resizing READ resizing NOTIFY resizingChanged)
     Q_PROPERTY(bool activated READ activated NOTIFY activatedChanged)
+// QDoc fails to parse the property type that includes the keyword 'enum'
+#ifndef Q_CLANG_QDOC
     Q_PROPERTY(enum DecorationMode decorationMode READ decorationMode NOTIFY decorationModeChanged)
+#else
+    Q_PROPERTY(DecorationMode decorationMode READ decorationMode NOTIFY decorationModeChanged)
+#endif
 public:
     enum State : uint {
         MaximizedState  = 1,
diff --git a/src/compositor/extensions/qwaylandxdgshellv5.cpp b/src/compositor/extensions/qwaylandxdgshellv5.cpp
index fab3c841a..337540fc3 100644
--- a/src/compositor/extensions/qwaylandxdgshellv5.cpp
+++ b/src/compositor/extensions/qwaylandxdgshellv5.cpp
@@ -591,7 +591,7 @@ QByteArray QWaylandXdgShellV5::interfaceName()
 }
 
 /*!
- * \qmlmethod void QtWaylandCompositor::XdgShellV5::ping()
+ * \qmlmethod void QtWaylandCompositor::XdgShellV5::ping(WaylandClient client)
  *
  * Sends a ping event to the \a client. If the client replies to the event, the
  * pong signal will be emitted.
@@ -784,6 +784,36 @@ void QWaylandXdgShellV5::handleFocusChanged(QWaylandSurface *newSurface, QWaylan
  */
 
 /*!
+    \enum QWaylandXdgSurfaceV5::ResizeEdge
+
+    \value NoneEdge
+           No edge defined.
+    \value TopEdge
+           Top egde.
+    \value BottomEdge
+           Bottom edge.
+    \value LeftEdge
+           Left edge.
+    \value TopLeftEdge
+           Top-left edge.
+    \value BottomLeftEdge
+           Bottom-left edge.
+    \value RightEdge
+           Right edge.
+    \value TopRightEdge
+           Top-right edge.
+    \value BottomRightEdge
+           Bottom-right edge.
+ */
+
+/*!
+ * \fn QWaylandXdgSurfaceV5::setTopLevel()
+ *
+ * This signal is emitted when the parent surface is unset, effectively
+ * making the window top level.
+ */
+
+/*!
  * \qmlsignal QtWaylandCompositor::XdgSurfaceV5::setTopLevel()
  *
  * This signal is emitted when the parent surface is unset, effectively
@@ -791,6 +821,13 @@ void QWaylandXdgShellV5::handleFocusChanged(QWaylandSurface *newSurface, QWaylan
  */
 
 /*!
+ * \fn QWaylandXdgSurfaceV5::setTransient()
+ *
+ * This signal is emitted when the parent surface is set, effectively
+ * making the window transient.
+ */
+
+/*!
  * \qmlsignal QtWaylandCompositor::XdgSurfaceV5::setTransient()
  *
  * This signal is emitted when the parent surface is set, effectively