Add note about QgsMapCanvas::refresh() behavior

doc/api_break.dox

@@ -21,6 +21,10 @@ This page tries to maintain a list with incompatible changes that happened in pr
 \subsection qgis_api_break_mtr Multi-threaded Rendering
 
 <ul>
+<li>QgsMapCanvas::refresh() only schedules a map refresh (in near feature) and returns immediately - before it would do the drawing immediately
+and return when the map is redrawn. A call to refresh() will have no effect if there is already a scheduled pending refresh.
+When map canvas does actual rendering, it will first emit renderStarting() signal, once done it will emit mapCanvasRefreshed().
+The client code doing refresh() in order to later save map image should be updated to use new QgsMapRendererJob API which is better suited for such task.
 <li>QgsPluginLayer::draw() is now run in a background thread. It is recommended to implement newly added QgsPluginLayer::createMapRenderer()
 method instead of using QgsPluginLayer::draw().
 </ul>