more dox

python/core/auto_generated/qgsmapsettings.sip.in

@@ -21,10 +21,12 @@ The rendering itself is done by QgsMapRendererJob subclasses.
 In order to set up QgsMapSettings instance, it is necessary to set at least
 few members: extent, output size and layers.
 
-QgsMapSettings and QgsMapRendererJob (+subclasses) are intended to replace
-QgsMapRenderer class that existed before QGIS 2.4. The advantage of the new
-classes is that they separate the settings from the rendering and provide
-asynchronous API for map rendering.
+Some systems use high DPI scaling that is an alternative to the traditional
+DPI scaling. The operating system provides Qt with a scaling ratio and it
+scales window, event, and desktop geometry. The Cocoa platform plugin sets
+the scaling ratio as QWindow.devicePixelRatio().
+To properly render the map on such systems, the map settings device pixel
+ratio shall be set accordingly.
 
 .. versionadded:: 2.4
 %End
@@ -63,13 +65,15 @@ Sets the size of the resulting map image
     float devicePixelRatio() const;
 %Docstring
 Returns device pixel ratio
+Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
 
 .. versionadded:: 3.4
 %End
 
     void setDevicePixelRatio( float dpr );
 %Docstring
 Sets the device pixel ratio
+Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
 
 .. versionadded:: 3.4
 %End

src/core/qgsmapsettings.h

@@ -48,10 +48,12 @@ class QgsMapRendererJob;
  * In order to set up QgsMapSettings instance, it is necessary to set at least
  * few members: extent, output size and layers.
  *
- * QgsMapSettings and QgsMapRendererJob (+subclasses) are intended to replace
- * QgsMapRenderer class that existed before QGIS 2.4. The advantage of the new
- * classes is that they separate the settings from the rendering and provide
- * asynchronous API for map rendering.
+ * Some systems use high DPI scaling that is an alternative to the traditional
+ * DPI scaling. The operating system provides Qt with a scaling ratio and it
+ * scales window, event, and desktop geometry. The Cocoa platform plugin sets
+ * the scaling ratio as QWindow::devicePixelRatio().
+ * To properly render the map on such systems, the map settings device pixel
+ * ratio shall be set accordingly.
  *
  * \since QGIS 2.4
  */
@@ -83,12 +85,14 @@ class CORE_EXPORT QgsMapSettings
 
     /**
      * Returns device pixel ratio
+     * Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
      * \since QGIS 3.4
      */
     float devicePixelRatio() const;
 
     /**
      * Sets the device pixel ratio
+     * Common values are 1 for normal-dpi displays and 2 for high-dpi "retina" displays.
      * \since QGIS 3.4
      */
     void setDevicePixelRatio( float dpr );