4 files changed, 30 insertions, 8 deletions
diff --git a/src/gui/image/qicon.cpp b/src/gui/image/qicon.cpp
index ac95222c99..1e4a9ebe8c 100644
--- a/src/gui/image/qicon.cpp
+++ b/src/gui/image/qicon.cpp
@@ -989,10 +989,16 @@ void QIcon::addPixmap(const QPixmap &pixmap, Mode mode, State state)
     QImageWriter::supportedImageFormats() functions to retrieve a
     complete list of the supported file formats.
 
-    Note: When you add a non-empty filename to a QIcon, the icon becomes
+    If a high resolution version of the image exists (identified by
+    the suffix \c @2x on the base name), it is automatically loaded
+    and added with the \e{device pixel ratio} set to a value of 2.
+    This can be disabled by setting the environment variable
+    \c QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING (see QImageReader).
+
+    \note When you add a non-empty filename to a QIcon, the icon becomes
     non-null, even if the file doesn't exist or points to a corrupt file.
 
-    \sa addPixmap()
+    \sa addPixmap(), QPixmap::devicePixelRatio()
  */
 void QIcon::addFile(const QString &fileName, const QSize &size, Mode mode, State state)
 {
diff --git a/src/gui/image/qimage.cpp b/src/gui/image/qimage.cpp
index 16696f611d..c3b4b1444a 100644
--- a/src/gui/image/qimage.cpp
+++ b/src/gui/image/qimage.cpp
@@ -1391,14 +1391,14 @@ QVector<QRgb> QImage::colorTable() const
 
 /*!
     Returns the device pixel ratio for the image. This is the
-    ratio between image pixels and device-independent pixels.
+    ratio between \e{device pixels} and \e{device independent pixels}.
 
     Use this function when calculating layout geometry based on
     the image size: QSize layoutSize = image.size() / image.devicePixelRatio()
 
     The default value is 1.0.
 
-    \sa setDevicePixelRatio()
+    \sa setDevicePixelRatio(), QImageReader
 */
 qreal QImage::devicePixelRatio() const
 {
@@ -1423,7 +1423,8 @@ qreal QImage::devicePixelRatio() const
     image size will take the ratio into account:
     QSize layoutSize = image.size() / image.devicePixelRatio()
     The net effect of this is that the image is displayed as
-    high-dpi image rather than a large image.
+    high-DPI image rather than a large image
+    (see \l{Drawing High Resolution Versions of Pixmaps and Images}).
 
     \sa devicePixelRatio()
 */
diff --git a/src/gui/image/qimagereader.cpp b/src/gui/image/qimagereader.cpp
index 3c75202766..3bf002373c 100644
--- a/src/gui/image/qimagereader.cpp
+++ b/src/gui/image/qimagereader.cpp
@@ -74,6 +74,8 @@
     that occurred, or errorString() to get a human readable
     description of what went wrong.
 
+    \section1 Formats
+
     Call supportedImageFormats() for a list of formats that
     QImageReader can read. QImageReader supports all built-in image
     formats, in addition to any image format plugins that support
@@ -85,7 +87,19 @@
     stream contents. You can enable or disable this feature, by calling
     setAutoDetectImageFormat().
 
+    \section1 High Resolution Versions of Images
+
+    It is possible to provide high resolution versions of images should a scaling
+    between \e{device pixels} and \e{device independent pixels} be in effect.
+
+    The high resolution version is marked by the suffix \c @2x on the base name.
+    The image read will have its \e{device pixel ratio} set to a value of 2.
+
+    This can be disabled by setting the environment variable
+    \c QT_HIGHDPI_DISABLE_2X_IMAGE_LOADING.
+
     \sa QImageWriter, QImageIOHandler, QImageIOPlugin, QMimeDatabase
+    \sa QImage::devicePixelRatio(), QPixmap::devicePixelRatio(), QIcon, QPainter::drawPixmap(), QPainter::drawImage(), Qt::AA_UseHighDpiPixmaps
 */
 
 /*!
diff --git a/src/gui/image/qpixmap.cpp b/src/gui/image/qpixmap.cpp
index 2d41ca7e24..88ce48f0e8 100644
--- a/src/gui/image/qpixmap.cpp
+++ b/src/gui/image/qpixmap.cpp
@@ -648,14 +648,14 @@ void QPixmap::setMask(const QBitmap &mask)
 
 /*!
     Returns the device pixel ratio for the pixmap. This is the
-    ratio between pixmap pixels and device-independent pixels.
+    ratio between \e{device pixels} and \e{device independent pixels}.
 
     Use this function when calculating layout geometry based on
     the pixmap size: QSize layoutSize = image.size() / image.devicePixelRatio()
 
     The default value is 1.0.
 
-    \sa setDevicePixelRatio()
+    \sa setDevicePixelRatio(), QImageReader
 */
 qreal QPixmap::devicePixelRatio() const
 {
@@ -680,7 +680,8 @@ qreal QPixmap::devicePixelRatio() const
     pixmap size will take the ratio into account:
     QSize layoutSize = pixmap.size() / pixmap.devicePixelRatio()
     The net effect of this is that the pixmap is displayed as
-    high-dpi pixmap rather than a large pixmap.
+    high-DPI pixmap rather than a large pixmap
+    (see \l{Drawing High Resolution Versions of Pixmaps and Images}).
 
         \sa devicePixelRatio()
 */