Doc: Fix qdoc warnings

Adopt the documentation we've added in dev.

Change-Id: Ic877e391b17b4b008f9f8543019f3944eb264475
Reviewed-by: Safiyyah Moosa <safiyyah.moosa@qt.io>
Reviewed-by: Paul Wicking <paul.wicking@qt.io>
(cherry picked from commit cd3a9cd96478b4b4e906ec025ae5574198801b6d)
Reviewed-by: Ulf Hermann <ulf.hermann@qt.io>
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>

2 files changed, 41 insertions, 4 deletions

diff --git a/src/quick/handlers/qquickpointerhandler.cpp b/src/quick/handlers/qquickpointerhandler.cpp
index 1de0a02055..7cbbd7742c 100644
--- a/src/quick/handlers/qquickpointerhandler.cpp
+++ b/src/quick/handlers/qquickpointerhandler.cpp
@@ -706,6 +706,18 @@ void QQuickPointerHandler::setActive(bool active)
     }
 }
 
+/*!
+    This function can be overridden to implement whatever behavior a specific
+    subclass is intended to have:
+    \list
+        \li Handle all the event's QPointerEvent::points() for which
+        wantsEventPoint() already returned \c true.
+        \li Call setPassiveGrab() setExclusiveGrab() or cancelAllGrabs() as
+        necessary.
+        \li Call QEvent::accept() to stop propagation, or ignore() to allow it
+        to keep going.
+    \endlist
+*/
 void QQuickPointerHandler::handlePointerEventImpl(QPointerEvent *)
 {
 }
diff --git a/src/quick/util/qquickdeliveryagent.cpp b/src/quick/util/qquickdeliveryagent.cpp
index 572e65b257..1b6a3bd611 100644
--- a/src/quick/util/qquickdeliveryagent.cpp
+++ b/src/quick/util/qquickdeliveryagent.cpp
@@ -1873,11 +1873,36 @@ void QQuickDeliveryAgentPrivate::deliverPointerEvent(QPointerEvent *event)
     lastUngrabbed = nullptr;
 }
 
-// check if item or any of its child items contain the point, or if any pointer handler "wants" the point
+/*! \internal
+    Returns a list of all items that are spatially relevant to receive \a event
+    occurring at \a point, starting with \a item and recursively checking all
+    the children.
+    \list
+        \li If an item has pointer handlers, call
+        QQuickPointerHandler::wantsEventPoint()
+        on every handler to decide whether the item is eligible.
+        \li Otherwise, if \a checkMouseButtons is \c true, it means we are
+        finding targets for a mouse event, so no item for which
+        acceptedMouseButtons() is NoButton will be added.
+        \li Otherwise, if \a checkAcceptsTouch is \c true, it means we are
+        finding targets for a touch event, so either acceptTouchEvents() must
+        return true \e or it must accept a synthesized mouse event. I.e. if
+        acceptTouchEvents() returns false, it gets added only if
+        acceptedMouseButtons() is true.
+        \li If QQuickItem::clip() is \c true \e and the \a point is outside of
+        QQuickItem::clipRect(), its children are also omitted. (We stop the
+        recursion, because any clipped-off portions of children under \a point
+        are invisible.)
+        \li Ignore any item in a subscene that "belongs to" a different
+        DeliveryAgent. (In current practice, this only happens in 2D scenes in
+        Qt Quick 3D.)
+    \endlist
+
+    The list returned from this function is the list of items that will be
+    "visited" when delivering any event for which QPointerEvent::isBeginEvent()
+    is \c true.
+*/
 // FIXME: should this be iterative instead of recursive?
-// If checkMouseButtons is true, it means we are finding targets for a mouse event, so no item for which acceptedMouseButtons() is NoButton will be added.
-// If checkAcceptsTouch is true, it means we are finding targets for a touch event, so either acceptTouchEvents() must return true OR
-// it must accept a synth. mouse event, thus if acceptTouchEvents() returns false but acceptedMouseButtons() is true, gets added; if not, it doesn't.
 QVector<QQuickItem *> QQuickDeliveryAgentPrivate::pointerTargets(QQuickItem *item, const QPointerEvent *event, const QEventPoint &point,
                                                           bool checkMouseButtons, bool checkAcceptsTouch) const
 {