Update doc.

Move to the class documentation in the cpp file,
focus on documenting the class and not necessarily
high-dpi scaling in general.

Change-Id: I4f04398904325b2f9061db8d3a82cd362276e977
Reviewed-by: Friedemann Kleint <Friedemann.Kleint@theqtcompany.com>
Reviewed-by: Paul Olav Tvete <paul.tvete@theqtcompany.com>

2 files changed, 36 insertions, 25 deletions

diff --git a/src/gui/kernel/qhighdpiscaling.cpp b/src/gui/kernel/qhighdpiscaling.cpp
index be127a54f3..20c7c6ca2a 100644
--- a/src/gui/kernel/qhighdpiscaling.cpp
+++ b/src/gui/kernel/qhighdpiscaling.cpp
@@ -88,15 +88,49 @@ static inline qreal initialScaleFactor()
     \ingroup qpa
 
     \brief Collection of utility functions for UI scaling.
-*/
 
+    QHighDpiScaling implements utility functions for high-dpi scaling for use
+    on operating systems that provide limited support for native scaling. In
+    addition this functionality can be used for simulation and testing purposes.
+
+    The functions support scaling between the device independent coordinate
+    system used by Qt applications and the native coordinate system used by
+    the platform plugins. Intended usage locations are the low level / platform
+    plugin interfacing parts of QtGui, for example the QWindow, QScreen and
+    QWindowSystemInterface implementation.
+
+    The coordinate system scaling is enabled by setting one or more scale
+    factors. These will then be factored into the value returned by the
+    devicePixelRatio() accessors (any native scale factor will also be
+    included in this value). Several setters are available:
+
+    - A process-global scale factor
+        - QT_SCALE_FACTOR (environment variable)
+        - QHighDpiScaling::setGlobalFactor()
+
+    - A per-screen scale factor
+        - QT_AUTO_SCALE_FACTOR (environment variable)
+          Setting this to a true-ish value will make QHighDpiScaling
+          call QPlatformScreen::pixelDensity()
+        - QHighDpiScaling::setScreenFactor(screen, factor);
+
+    All scale factors are of type qreal.
+
+    The main scaling functions for use in QtGui are:
+        T toNativePixels(T, QWindow *)
+        T fromNativePixels(T, QWindow*)
+    Where T is QPoint, QSize, QRect etc.
+*/
 
 qreal QHighDpiScaling::m_factor;
-
 bool QHighDpiScaling::m_active; //"overall active" - is there any scale factor set.
 bool QHighDpiScaling::m_perScreenActive; // different screens may have different scale
 bool QHighDpiScaling::m_usePixelDensity; // use scale factor from platform plugin
 
+/*
+    Initializes the QHighDpiScaling global variables. Called before the
+    platform plugin is created.
+*/
 void QHighDpiScaling::initHighDPiScaling()
 {
     m_factor = initialScaleFactor();
diff --git a/src/gui/kernel/qhighdpiscaling_p.h b/src/gui/kernel/qhighdpiscaling_p.h
index 8347214823..bf967d10ad 100644
--- a/src/gui/kernel/qhighdpiscaling_p.h
+++ b/src/gui/kernel/qhighdpiscaling_p.h
@@ -51,29 +51,6 @@
 #include <QtGui/qscreen.h>
 #include <QtGui/qwindow.h>
 
-// This file implmements utility functions for high-dpi scaling on operating
-// systems that do not provide native scaling support.
-//
-// The functions support creating a logical device-independent
-// coordinate system which is related to the device pixel coordinate
-// through a scaling factor.
-//
-// Several scaling factors can be set:
-//   - A process-global scale factor
-//       - the QT_SCALE_FACTOR environment variable.
-//       - QHighDpiScaling::setFactor(factor);
-//   - A per-window scale factor
-//       - QHighDpiScaling::setWindowFactor(window, factor);
-//
-// With these functions in use  most of the Qt API will then operate in
-// the device-independent coordinate system. For example, setting
-// the scale factor to 2.0 will make Qt see half of the "device"
-// window geometry. Desktop and event geometry will be scaled
-// to match.
-//
-// Integer scaling factors work best. Glitch-free graphics at non-integer
-// scaling factors can not be guaranteed.
-
 QT_BEGIN_NAMESPACE
 
 Q_DECLARE_LOGGING_CATEGORY(lcScaling);