Doc: fix qdoc errors and clarify purpose of deviceTransform parameter

in new overloads.

Reviewed-By: bnilsen

3 files changed, 58 insertions, 39 deletions

diff --git a/src/gui/graphicsview/qgraphicsscene.cpp b/src/gui/graphicsview/qgraphicsscene.cpp
index 06333ae..6b6080b 100644
--- a/src/gui/graphicsview/qgraphicsscene.cpp
+++ b/src/gui/graphicsview/qgraphicsscene.cpp
@@ -1626,6 +1626,20 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
 */
 
 /*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(qreal x, qreal y, qreal w, qreal h,
+        Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
+    \overload
+    \since 4.6
+
+    Returns all visible items that, depending on \a mode, are either inside or
+    intersect with the rectangle defined by \a x, \a y, \a w and \a h, in a list
+    sorted using \a order.
+
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
+*/
+
+/*!
     \overload
 
     Returns all visible items that, depending on \a mode, are either inside or
@@ -1660,13 +1674,16 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemS
 }
 
 /*!
+    \since 4.6
+
     Returns all visible items that, depending on \a mode, are at the specified \a pos
-    and return a list sorted using \a order.
+    in a list sorted using \a order.
 
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with \a pos are returned.
 
-    \a deviceTransform is the transformation apply to the view.
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
 
     \sa itemAt()
 */
@@ -1679,6 +1696,7 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelecti
 
 /*!
     \overload
+    \since 4.6
 
     Returns all visible items that, depending on \a mode, are either inside or
     intersect with the specified \a rect and return a list sorted using \a order.
@@ -1686,7 +1704,8 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelecti
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a rect are returned.
 
-    \a deviceTransform is the transformation apply to the view.
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
 
     \sa itemAt()
 */
@@ -1699,6 +1718,7 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
 
 /*!
     \overload
+    \since 4.6
 
     Returns all visible items that, depending on \a mode, are either inside or
     intersect with the specified \a polygon and return a list sorted using \a order.
@@ -1706,7 +1726,8 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a polygon are returned.
 
-    \a deviceTransform is the transformation apply to the view.
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
 
     \sa itemAt()
 */
@@ -1718,7 +1739,8 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
 }
 
 /*!
-   \overload
+    \overload
+    \since 4.6
 
     Returns all visible items that, depending on \a mode, are either inside or
     intersect with the specified \a path and return a list sorted using \a order.
@@ -1726,7 +1748,8 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a path are returned.
 
-    \a deviceTransform is the transformation apply to the view.
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
 
     \sa itemAt()
 */
@@ -1767,8 +1790,6 @@ QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
 }
 
 /*!
-    \fn QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position) const
-
     Returns the topmost visible item at the specified \a position, or 0 if
     there are no items at this position.
 
@@ -1776,15 +1797,29 @@ QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
 
     \sa items(), collidingItems(), QGraphicsItem::setZValue()
 */
-QGraphicsItem *QGraphicsScene::itemAt(const QPointF &pos) const
+QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position) const
 {
-    QList<QGraphicsItem *> itemsAtPoint = items(pos);
+    QList<QGraphicsItem *> itemsAtPoint = items(position);
     return itemsAtPoint.isEmpty() ? 0 : itemsAtPoint.first();
 }
 
-QGraphicsItem *QGraphicsScene::itemAt(const QPointF &pos, const QTransform &deviceTransform) const
+/*!
+    \overload
+    \since 4.6
+
+    Returns the topmost visible item at the specified \a position, or 0
+    if there are no items at this position.
+
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
+
+    \note The topmost item is the one with the highest Z-value.
+
+    \sa items(), collidingItems(), QGraphicsItem::setZValue()
+    */
+QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform &deviceTransform) const
 {
-    QList<QGraphicsItem *> itemsAtPoint = items(pos, Qt::IntersectsItemShape,
+    QList<QGraphicsItem *> itemsAtPoint = items(position, Qt::IntersectsItemShape,
                                                 Qt::AscendingOrder, deviceTransform);
     return itemsAtPoint.isEmpty() ? 0 : itemsAtPoint.first();
 }
@@ -1869,11 +1904,14 @@ void QGraphicsScene::setSelectionArea(const QPainterPath &path, Qt::ItemSelectio
 
 /*!
     \overload
-    \since 4.3
+    \since 4.6
 
     Sets the selection area to \a path using \a mode to determine if items are
     included in the selection area.
 
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
+
     \sa clearSelection(), selectionArea()
 */
 void QGraphicsScene::setSelectionArea(const QPainterPath &path, Qt::ItemSelectionMode mode,
diff --git a/src/gui/graphicsview/qgraphicssceneindex.cpp b/src/gui/graphicsview/qgraphicssceneindex.cpp
index 5619b59..ab5ca85 100644
--- a/src/gui/graphicsview/qgraphicssceneindex.cpp
+++ b/src/gui/graphicsview/qgraphicssceneindex.cpp
@@ -553,20 +553,9 @@ QList<QGraphicsItem *> QGraphicsSceneIndex::estimateTopLevelItems(const QRectF &
 }
 
 /*!
-    \fn virtual QList<QGraphicsItem *>
-    QGraphicsSceneIndex::estimateItems(const QRectF &rect, Qt::SortOrder
-    order, const QTransform &deviceTransform) const = 0
-
-    This pure virtual function return an estimation of items in the \a rect.
-    This method return a list sorted using \a order.
-
-    \a deviceTransform is the transformation apply to the view.
-*/
-
-/*!
-    \fn virtual QList<QGraphicsItem *>
-    QGraphicsSceneIndex::items(Qt::SortOrder order = Qt::AscendingOrder) const
-    = 0; This pure virtual function all items in the index and sort them using
+    \fn QList<QGraphicsItem *> QGraphicsSceneIndex::items(Qt::SortOrder order = Qt::AscendingOrder) const
+    
+    This pure virtual function all items in the index and sort them using
     \a order.
 */
 
diff --git a/src/gui/graphicsview/qgraphicsscenelinearindex.cpp b/src/gui/graphicsview/qgraphicsscenelinearindex.cpp
index f13b17b..45cf702 100644
--- a/src/gui/graphicsview/qgraphicsscenelinearindex.cpp
+++ b/src/gui/graphicsview/qgraphicsscenelinearindex.cpp
@@ -44,9 +44,7 @@
     \brief The QGraphicsSceneLinearIndex class provides an implementation of
     a linear indexing algorithm for discovering items in QGraphicsScene.
     \since 4.6
-    \ingroup multimedia
     \ingroup graphicsview-api
-    \mainclass
     \internal
 
     QGraphicsSceneLinearIndex index is default linear implementation to discover items.
@@ -71,32 +69,26 @@
 
 
 /*!
-    \fn virtual QList<QGraphicsItem *> QGraphicsSceneLinearIndex::estimateItems(const QRectF &rect, Qt::SortOrder order) const;
+    \fn virtual QList<QGraphicsItem *> QGraphicsSceneLinearIndex::estimateItems(const QRectF &rect, Qt::SortOrder order) const
 
     Returns an estimation visible items that are either inside or
     intersect with the specified \a rect and return a list sorted using \a order.
 */
 
 /*!
-    \fn QRectF QGraphicsSceneLinearIndex::indexedRect() const;
-    \reimp
-    Return the rect indexed by the the index.
-*/
-
-/*!
-    \fn void QGraphicsSceneLinearIndex::clear();
+    \fn void QGraphicsSceneLinearIndex::clear()
     \reimp
     Clear the all the BSP index.
 */
 
 /*!
-    \fn virtual void QGraphicsSceneLinearIndex::addItem(QGraphicsItem *item);
+    \fn virtual void QGraphicsSceneLinearIndex::addItem(QGraphicsItem *item)
 
     Add the \a item into the index.
 */
 
 /*!
-    \fn virtual void QGraphicsSceneLinearIndex::removeItem(QGraphicsItem *item);
+    \fn virtual void QGraphicsSceneLinearIndex::removeItem(QGraphicsItem *item)
 
     Add the \a item from the index.
 */