Doc: Updated docs for collision between QGraphicsItems

Task-number: 252287

1 files changed, 20 insertions, 8 deletions

diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index 3e8d38f..2ec1c44 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -3235,10 +3235,16 @@ bool QGraphicsItem::contains(const QPointF &point) const
 }
 
 /*!
-    Returns true if this item collides with \a other; otherwise returns false.
-    The ways items collide is determined by \a mode. The default value for \a
-    mode is Qt::IntersectsItemShape; \a other collides with this item if it
-    either intersects, contains, or is contained by this item's shape.
+
+    Returns true if this item collides with \a other; otherwise
+    returns false.
+
+    The \a mode is applied to \a other, and the resulting shape or
+    bounding rectangle is then compared to this item's shape. The
+    default value for \a mode is Qt::IntersectsItemShape; \a other
+    collides with this item if it either intersects, contains, or is
+    contained by this item's shape (see Qt::ItemSelectionMode for
+    details).
 
     The default implementation is based on shape intersection, and it calls
     shape() on both items. Because the complexity of arbitrary shape-shape
@@ -3293,6 +3299,11 @@ bool QGraphicsItem::collidesWithItem(const QGraphicsItem *other, Qt::ItemSelecti
     Qt::IntersectsItemShape; \a path collides with this item if it either
     intersects, contains, or is contained by this item's shape.
 
+    Note that this function checks whether the item's shape or
+    bounding rectangle (depending on \a mode) is contained within \a
+    path, and not whether \a path is contained within the items shape
+    or bounding rectangle. 
+
     \sa collidesWithItem(), contains(), shape()
 */
 bool QGraphicsItem::collidesWithPath(const QPainterPath &path, Qt::ItemSelectionMode mode) const
@@ -3333,11 +3344,12 @@ bool QGraphicsItem::collidesWithPath(const QPainterPath &path, Qt::ItemSelection
 /*!
     Returns a list of all items that collide with this item.
 
-    The way collisions are detected is determined by \a mode. The default
-    value for \a mode is Qt::IntersectsItemShape; All items whose shape
-    intersects or is contained by this item's shape are returned.
+    The way collisions are detected is determined by applying \a mode
+    to items that are compared to this item, i.e., each item's shape
+    or bounding rectangle is checked against this item's shape. The
+    default value for \a mode is Qt::IntersectsItemShape.
 
-    \sa QGraphicsScene::collidingItems(), collidesWithItem()
+    \sa collidesWithItem()
 */
 QList<QGraphicsItem *> QGraphicsItem::collidingItems(Qt::ItemSelectionMode mode) const
 {