From ca8a6e6ee1c2439dbe439244b61f86cf062f88d5 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Tue, 12 Nov 2019 23:18:42 +0100 Subject: 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 --- .../compositor_api/qwaylandcompositor.cpp | 24 +++++++------ .../compositor_api/qwaylandquickitem.cpp | 19 +++++++++-- src/compositor/compositor_api/qwaylandseat.cpp | 10 ++++-- .../doc/src/qtwaylandcompositor-overview.qdoc | 2 +- .../extensions/qwaylandidleinhibitv1.cpp | 4 +-- .../extensions/qwaylandiviapplication.cpp | 2 +- .../extensions/qwaylandquickshellintegration.cpp | 2 +- src/compositor/extensions/qwaylandshellsurface.cpp | 2 +- src/compositor/extensions/qwaylandxdgoutputv1.cpp | 4 +-- src/compositor/extensions/qwaylandxdgshell.h | 5 +++ src/compositor/extensions/qwaylandxdgshellv5.cpp | 39 +++++++++++++++++++++- 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. @@ -783,6 +783,36 @@ void QWaylandXdgShellV5::handleFocusChanged(QWaylandSurface *newSurface, QWaylan * \deprecated */ +/*! + \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() * @@ -790,6 +820,13 @@ void QWaylandXdgShellV5::handleFocusChanged(QWaylandSurface *newSurface, QWaylan * making the window top level. */ +/*! + * \fn QWaylandXdgSurfaceV5::setTransient() + * + * This signal is emitted when the parent surface is set, effectively + * making the window transient. + */ + /*! * \qmlsignal QtWaylandCompositor::XdgSurfaceV5::setTransient() * -- cgit v1.2.3