Update documentation for sorting / stacking order in Graphics View.

Remove all references to "elevation" and how items are sorted by their
"z order". Now use "stacking order" and only refer to "z-value" when
discussing sibling order. Move almost all sorting docs from the
QGraphicsItem::setZValue() function to a general overview section in
QGraphicsItem's class documentation.

Reviewed-by: David Boddie

3 files changed, 202 insertions, 164 deletions

diff --git a/src/gui/graphicsview/qgraphicsitem.cpp b/src/gui/graphicsview/qgraphicsitem.cpp
index bc9c73f..0690690 100644
--- a/src/gui/graphicsview/qgraphicsitem.cpp
+++ b/src/gui/graphicsview/qgraphicsitem.cpp
@@ -186,6 +186,49 @@
     high z-values. Stacking order applies to sibling items; parents are always
     drawn before their children.
 
+    \section1 Sorting
+
+    All items are drawn in a defined, stable order, and this same order decides
+    which items will receive mouse input first when you click on the scene.
+    Normally you don't have to worry about sorting, as the items follow a
+    "natural order", following the logical structure of the scene.
+
+    An item's children are stacked on top of the parent, and sibling items are
+    stacked by insertion order (i.e., in the same order that they were either
+    added to the scene, or added to the same parent). If you add item A, and
+    then B, then B will be on top of A. If you then add C, the items' stacking
+    order will be A, then B, then C.
+
+    \image graphicsview-zorder.png
+
+    This example shows the stacking order of all limbs of the robot from the
+    \l{graphicsview/dragdroprobot}{Drag and Drop Robot} example. The torso is
+    the root item (all other items are children or descendants of the torso),
+    so it is drawn first. Next, the head is drawn, as it is the first item in
+    the torso's list of children. Then the upper left arm is drawn. As the
+    lower arm is a child of the upper arm, the lower arm is then drawn,
+    followed by the upper arm's next sibling, which is the upper right arm, and
+    so on.
+
+    For advanced users, there are ways to alter how your items are sorted:
+
+    \list
+    \o You can call setZValue() on an item to explicitly stack it on top of, or
+    under, other sibling items. The default Z value for an item is 0. Items
+    with the same Z value are stacked by insertion order.
+
+    \o You can call stackBefore() to reorder the list of children. This will
+    directly modify the insertion order.
+
+    \o You can set the ItemStacksBehindParent flag to stack a child item behind
+    its parent.
+    \endlist
+
+    The stacking order of two sibling items also counts for each item's
+    children and descendant items. So if one item is on top of another, then
+    all its children will also be on top of all the other item's children as
+    well.
+
     \section1 Events
 
     QGraphicsItem receives events from QGraphicsScene through the virtual
@@ -1487,10 +1530,12 @@ QList<QGraphicsItem *> QGraphicsItem::children() const
 /*!
     \since 4.4
 
-    Returns a list of this item's children. The items are returned in no
-    particular order.
+    Returns a list of this item's children.
 
-    \sa setParentItem()
+    The items are sorted by stacking order. This takes into account both the
+    items' insertion order and their Z-values.
+
+    \sa setParentItem(), zValue(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsItem::childItems() const
 {
@@ -4090,12 +4135,12 @@ void QGraphicsItem::advance(int phase)
 }
 
 /*!
-    Returns the Z-value, or the elevation, of the item. The Z-value decides
-    the stacking order of sibling (neighboring) items.
+    Returns the Z-value of the item. The Z-value affects the stacking order of
+    sibling (neighboring) items.
 
     The default Z-value is 0.
 
-    \sa setZValue()
+    \sa setZValue(), {QGraphicsItem#Sorting}{Sorting}, stackBefore(), ItemStacksBehindParent
 */
 qreal QGraphicsItem::zValue() const
 {
@@ -4103,33 +4148,18 @@ qreal QGraphicsItem::zValue() const
 }
 
 /*!
-    Sets the Z-value, or the elevation, of the item, to \a z. The elevation
-    decides the stacking order of sibling (neighboring) items. An item of high
-    Z-value will be drawn on top of an item with a lower Z-value if they share
-    the same parent item. In addition, children of an item will always be
-    drawn on top of the parent, regardless of the child's Z-value. Sibling
-    items that share the same Z-value will be drawn in order of insertion; the
-    last inserted child is stacked above previous children.
-
-    \img graphicsview-zorder.png
+    Sets the Z-value of the item to \a z. The Z value decides the stacking
+    order of sibling (neighboring) items. A sibling item of high Z value will
+    always be drawn on top of another sibling item with a lower Z value.
 
-    Children of different parents are stacked according to the Z-value of
-    each item's ancestor item which is an immediate child of the two
-    items' closest common ancestor. For example, a robot item might
-    define a torso item as the parent of a head item, two arm items,
-    and two upper-leg items. The upper-leg items would each be parents
-    of one lower-leg item, and each lower-leg item would be parents of
-    one foot item.  The stacking order of the feet is the same as the
-    stacking order of each foot's ancestor that is an immediate child
-    of the two feet's common ancestor (i.e., the torso item); so the
-    feet are stacked in the same order as the upper-leg items,
-    regardless of each foot's Z-value.
+    If you restore the Z value, the item's insertion order will decide its
+    stacking order.
 
     The Z-value does not affect the item's size in any way.
 
     The default Z-value is 0.
 
-    \sa zValue()
+    \sa zValue(), {QGraphicsItem#Sorting}{Sorting}, stackBefore(), ItemStacksBehindParent
 */
 void QGraphicsItem::setZValue(qreal z)
 {
@@ -4192,12 +4222,13 @@ void QGraphicsItemPrivate::ensureSequentialSiblingIndex()
     The \a sibling must have the same Z value as this item, otherwise calling
     this function will have no effect.
 
-    By default, all items are stacked by insertion order (i.e., the first item
-    you add is drawn before the next item you add). If two items' Z values are
-    different, then the item with the highest Z value is drawn on top. When the
-    Z values are the same, the insertion order will decide the stacking order.
+    By default, all sibling items are stacked by insertion order (i.e., the
+    first item you add is drawn before the next item you add). If two items' Z
+    values are different, then the item with the highest Z value is drawn on
+    top. When the Z values are the same, the insertion order will decide the
+    stacking order.
 
-    \sa setZValue(), ItemStacksBehindParent
+    \sa setZValue(), ItemStacksBehindParent, {QGraphicsItem#Sorting}{Sorting}
 */
 void QGraphicsItem::stackBefore(const QGraphicsItem *sibling)
 {
diff --git a/src/gui/graphicsview/qgraphicsscene.cpp b/src/gui/graphicsview/qgraphicsscene.cpp
index a1ff6d2..1226722 100644
--- a/src/gui/graphicsview/qgraphicsscene.cpp
+++ b/src/gui/graphicsview/qgraphicsscene.cpp
@@ -1759,10 +1759,10 @@ QRectF QGraphicsScene::itemsBoundingRect() const
     return boundingRect;
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items() const
-  Returns a list of all items on the scene, in no particular order.
+/*!
+    Returns a list of all items in the scene in descending stacking order.
 
-  \sa addItem(), removeItem()
+    \sa addItem(), removeItem(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items() const
 {
@@ -1770,11 +1770,11 @@ QList<QGraphicsItem *> QGraphicsScene::items() const
     return d->index->items(Qt::DescendingOrder);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order) const
-  Returns an ordered list of all items on the scene. \a order decides the
-  sorting.
+/*!
+    Returns an ordered list of all items on the scene. \a order decides the
+    stacking order.
 
-  \sa addItem(), removeItem()
+    \sa addItem(), removeItem(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order) const
 {
@@ -1782,18 +1782,18 @@ QList<QGraphicsItem *> QGraphicsScene::items(Qt::SortOrder order) const
     return d->index->items(order);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos) const
-  \obsolete
+/*!
+    \obsolete
 
-  Returns all visible items at position \a pos in the scene. The items are
-  listed in descending stacking order (i.e., the first item in the list is the
-  top-most item, and the last item is the bottom-most item).
+    Returns all visible items at position \a pos in the scene. The items are
+    listed in descending stacking order (i.e., the first item in the list is the
+    top-most item, and the last item is the bottom-most item).
 
-  This function is deprecated and returns incorrect results if the scene
-  contains items that ignore transformations. Use the overload that takes
-  a QTransform instead.
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
 
-  \sa itemAt()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos) const
 {
@@ -1801,21 +1801,21 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos) const
     return d->index->items(pos, Qt::IntersectsItemShape, Qt::DescendingOrder);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rectangle, Qt::ItemSelectionMode mode) const
-  \overload
-  \obsolete
+/*!
+    \overload
+    \obsolete
 
-  Returns all visible items that, depending on \a mode, are either inside or
-  intersect with the specified \a rectangle.
+    Returns all visible items that, depending on \a mode, are either inside or
+    intersect with the specified \a rectangle.
 
-  The default value for \a mode is Qt::IntersectsItemShape; all items whose
-  exact shape intersects with or is contained by \a rectangle are returned.
+    The default value for \a mode is Qt::IntersectsItemShape; all items whose
+    exact shape intersects with or is contained by \a rectangle are returned.
 
-  This function is deprecated and returns incorrect results if the scene
-  contains items that ignore transformations. Use the overload that takes
-  a QTransform instead.
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
 
-  \sa itemAt()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rectangle, Qt::ItemSelectionMode mode) const
 {
@@ -1823,45 +1823,47 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rectangle, Qt::ItemSe
     return d->index->items(rectangle, mode, Qt::DescendingOrder);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(qreal x, qreal y, qreal w, qreal h, Qt::ItemSelectionMode mode) const
-  \obsolete
-  \since 4.3
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(qreal x, qreal y, qreal w, qreal h, Qt::ItemSelectionMode mode) const
+    \obsolete
+    \since 4.3
 
-  This convenience function is equivalent to calling items(QRectF(\a x, \a y, \a w, \a h), \a mode).
+    This convenience function is equivalent to calling items(QRectF(\a x, \a y, \a w, \a h), \a mode).
     
-  This function is deprecated and returns incorrect results if the scene
-  contains items that ignore transformations. Use the overload that takes
-  a QTransform instead.
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
 */
 
 /*!
-  \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
+    \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
 
-  \brief 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.
+    \brief 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.
+    \a deviceTransform is the transformation that applies to the view, and needs to
+    be provided if the scene contains items that ignore transformations.
 */
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode) const
-  \overload
-  \obsolete
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode) const
+    \overload
+    \obsolete
 
-  Returns all visible items that, depending on \a mode, are either inside or
-  intersect with the polygon \a polygon.
+    Returns all visible items that, depending on \a mode, are either inside or
+    intersect with the polygon \a polygon.
 
-  The default value for \a mode is Qt::IntersectsItemShape; all items whose
-  exact shape intersects with or is contained by \a polygon are returned.
+    The default value for \a mode is Qt::IntersectsItemShape; all items whose
+    exact shape intersects with or is contained by \a polygon are returned.
 
-  This function is deprecated and returns incorrect results if the scene
-  contains items that ignore transformations. Use the overload that takes
-  a QTransform instead.
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
 
-  \sa itemAt()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode) const
 {
@@ -1869,21 +1871,22 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
     return d->index->items(polygon, mode, Qt::DescendingOrder);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode) const
-  \overload
-  \obsolete
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode) const
+    \overload
+    \obsolete
 
-  Returns all visible items that, depending on \a path, are either inside or
-  intersect with the path \a path.
+    Returns all visible items that, depending on \a path, are either inside or
+    intersect with the path \a path.
 
-   The default value for \a mode is Qt::IntersectsItemShape; all items whose
-   exact shape intersects with or is contained by \a path are returned.
+    The default value for \a mode is Qt::IntersectsItemShape; all items whose
+    exact shape intersects with or is contained by \a path are returned.
 
-   This function is deprecated and returns incorrect results if the scene
-   contains items that ignore transformations. Use the overload that takes
-   a QTransform instead.
+    This function is deprecated and returns incorrect results if the scene
+    contains items that ignore transformations. Use the overload that takes
+    a QTransform instead.
 
-   \sa itemAt()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode) const
 {
@@ -1891,20 +1894,20 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemS
     return d->index->items(path, mode, Qt::DescendingOrder);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
-
-  \since 4.6
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
+    \since 4.6
 
-  \brief Returns all visible items that, depending on \a mode, are at
-  the specified \a pos in a list sorted using \a order.
+    \brief Returns all visible items that, depending on \a mode, are at
+    the specified \a pos 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.
+    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 that applies to the view, and needs to
-  be provided if the scene contains items that ignore transformations.
+    \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()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelectionMode mode,
                                              Qt::SortOrder order, const QTransform &deviceTransform) const
@@ -1913,21 +1916,22 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPointF &pos, Qt::ItemSelecti
     return d->index->items(pos, mode, order, deviceTransform);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
-  \overload
-  \since 4.6
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
+    \overload
+    \since 4.6
 
-  \brief 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.
+    \brief 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.
 
-  The default value for \a mode is Qt::IntersectsItemShape; all items whose
-  exact shape intersects with or is contained by \a rect are returned.
+    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 that applies to the view, and needs to
-  be provided if the scene contains items that ignore transformations.
+    \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()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelectionMode mode,
                                              Qt::SortOrder order, const QTransform &deviceTransform) const
@@ -1936,21 +1940,22 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QRectF &rect, Qt::ItemSelecti
     return d->index->items(rect, mode, order, deviceTransform);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
-  \overload
-  \since 4.6
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
+    \overload
+    \since 4.6
 
-  \brief 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.
+    \brief 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.
 
-  The default value for \a mode is Qt::IntersectsItemShape; all items whose
-  exact shape intersects with or is contained by \a polygon are returned.
+    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 that applies to the view, and needs to
-  be provided if the scene contains items that ignore transformations.
+    \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()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemSelectionMode mode,
                                              Qt::SortOrder order, const QTransform &deviceTransform) const
@@ -1959,21 +1964,22 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPolygonF &polygon, Qt::ItemS
     return d->index->items(polygon, mode, order, deviceTransform);
 }
 
-/*! \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
-  \overload
-  \since 4.6
+/*!
+    \fn QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode, Qt::SortOrder order, const QTransform &deviceTransform) const
+    \overload
+    \since 4.6
 
-  \brief 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.
+    \brief 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.
 
-  The default value for \a mode is Qt::IntersectsItemShape; all items whose
-  exact shape intersects with or is contained by \a path are returned.
+    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 that applies to the view, and needs to
-  be provided if the scene contains items that ignore transformations.
+    \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()
+    \sa itemAt(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemSelectionMode mode,
                                              Qt::SortOrder order, const QTransform &deviceTransform) const
@@ -1988,10 +1994,11 @@ QList<QGraphicsItem *> QGraphicsScene::items(const QPainterPath &path, Qt::ItemS
     detection is determined by \a mode. By default, all items whose shape
     intersects \a item or is contained inside \a item's shape are returned.
 
-    The items are returned in descending Z order (i.e., the first item in the
-    list is the top-most item, and the last item is the bottom-most item).
+    The items are returned in descending stacking order (i.e., the first item
+    in the list is the uppermost item, and the last item is the lowermost
+    item).
 
-    \sa items(), itemAt(), QGraphicsItem::collidesWithItem()
+    \sa items(), itemAt(), QGraphicsItem::collidesWithItem(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
                                                       Qt::ItemSelectionMode mode) const
@@ -2018,13 +2025,11 @@ QList<QGraphicsItem *> QGraphicsScene::collidingItems(const QGraphicsItem *item,
     Returns the topmost visible item at the specified \a position, or 0 if
     there are no items at this position.
 
-    \note The topmost item is the one with the highest Z-value.
-
     This function is deprecated and returns incorrect results if the scene
     contains items that ignore transformations. Use the overload that takes
     a QTransform instead.
 
-    \sa items(), collidingItems(), QGraphicsItem::setZValue()
+    \sa items(), collidingItems(), {QGraphicsItem#Sorting}{Sorting}
 */
 QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position) const
 {
@@ -2041,10 +2046,8 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position) const
     \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()
-    */
+    \sa items(), collidingItems(), {QGraphicsItem#Sorting}{Sorting}
+*/
 QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform &deviceTransform) const
 {
     QList<QGraphicsItem *> itemsAtPoint = items(position, Qt::IntersectsItemShape,
@@ -2065,8 +2068,6 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
 
     This convenience function is equivalent to calling \c
     {itemAt(QPointF(x, y), deviceTransform)}.
-
-    \note The topmost item is the one with the highest Z-value.
 */
 
 /*!
@@ -2083,8 +2084,6 @@ QGraphicsItem *QGraphicsScene::itemAt(const QPointF &position, const QTransform
     This function is deprecated and returns incorrect results if the scene
     contains items that ignore transformations. Use the overload that takes
     a QTransform instead.
-
-    \note The topmost item is the one with the highest Z-value.
 */
 
 /*!
@@ -2363,7 +2362,7 @@ void QGraphicsScene::destroyItemGroup(QGraphicsItemGroup *group)
     in the scene, then the item will be activated.
 
     \sa removeItem(), addEllipse(), addLine(), addPath(), addPixmap(),
-    addRect(), addText(), addWidget()
+    addRect(), addText(), addWidget(), {QGraphicsItem#Sorting}{Sorting}
 */
 void QGraphicsScene::addItem(QGraphicsItem *item)
 {
diff --git a/src/gui/graphicsview/qgraphicsview.cpp b/src/gui/graphicsview/qgraphicsview.cpp
index 98b2c9c..32747cc 100644
--- a/src/gui/graphicsview/qgraphicsview.cpp
+++ b/src/gui/graphicsview/qgraphicsview.cpp
@@ -2016,9 +2016,11 @@ void QGraphicsView::render(QPainter *painter, const QRectF &target, const QRect
 }
 
 /*!
-    Returns a list of all the items in the associated scene.
+    Returns a list of all the items in the associated scene, in descending
+    stacking order (i.e., the first item in the returned list is the uppermost
+    item).
 
-    \sa QGraphicsScene::items()
+    \sa QGraphicsScene::items(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsView::items() const
 {
@@ -2030,9 +2032,9 @@ QList<QGraphicsItem *> QGraphicsView::items() const
 
 /*!
     Returns a list of all the items at the position \a pos in the view. The
-    items are listed in descending Z order (i.e., the first item in the list
-    is the top-most item, and the last item is the bottom-most item). \a pos
-    is in viewport coordinates.
+    items are listed in descending stacking order (i.e., the first item in the
+    list is the uppermost item, and the last item is the lowermost item). \a
+    pos is in viewport coordinates.
 
     This function is most commonly called from within mouse event handlers in
     a subclass in QGraphicsView. \a pos is in untransformed viewport
@@ -2040,7 +2042,7 @@ QList<QGraphicsItem *> QGraphicsView::items() const
 
     \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsview.cpp 5
 
-    \sa QGraphicsScene::items(), QGraphicsItem::zValue()
+    \sa QGraphicsScene::items(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsView::items(const QPoint &pos) const
 {
@@ -2082,7 +2084,10 @@ QList<QGraphicsItem *> QGraphicsView::items(const QPoint &pos) const
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a rect are returned.
 
-    \sa itemAt(), items(), mapToScene()
+    The items are sorted in descending stacking order (i.e., the first item in
+    the returned list is the uppermost item).
+
+    \sa itemAt(), items(), mapToScene(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsView::items(const QRect &rect, Qt::ItemSelectionMode mode) const
 {
@@ -2110,7 +2115,10 @@ QList<QGraphicsItem *> QGraphicsView::items(const QRect &rect, Qt::ItemSelection
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a polygon are returned.
 
-    \sa itemAt(), items(), mapToScene()
+    The items are sorted by descending stacking order (i.e., the first item in
+    the returned list is the uppermost item).
+
+    \sa itemAt(), items(), mapToScene(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsView::items(const QPolygon &polygon, Qt::ItemSelectionMode mode) const
 {
@@ -2130,7 +2138,7 @@ QList<QGraphicsItem *> QGraphicsView::items(const QPolygon &polygon, Qt::ItemSel
     The default value for \a mode is Qt::IntersectsItemShape; all items whose
     exact shape intersects with or is contained by \a path are returned.
 
-    \sa itemAt(), items(), mapToScene()
+    \sa itemAt(), items(), mapToScene(), {QGraphicsItem#Sorting}{Sorting}
 */
 QList<QGraphicsItem *> QGraphicsView::items(const QPainterPath &path, Qt::ItemSelectionMode mode) const
 {
@@ -2149,7 +2157,7 @@ QList<QGraphicsItem *> QGraphicsView::items(const QPainterPath &path, Qt::ItemSe
 
     \snippet doc/src/snippets/code/src_gui_graphicsview_qgraphicsview.cpp 6
 
-    \sa items()
+    \sa items(), {QGraphicsItem#Sorting}{Sorting}
 */
 QGraphicsItem *QGraphicsView::itemAt(const QPoint &pos) const
 {