diff --git a/docs/doxygen/overviews/high_dpi.md b/docs/doxygen/overviews/high_dpi.md
index 4d33ed102a..ffc6e8fed0 100644
--- a/docs/doxygen/overviews/high_dpi.md
+++ b/docs/doxygen/overviews/high_dpi.md
@@ -285,6 +285,24 @@ XRC format has been updated to allow specifying wxBitmapBundle with
 multiple bitmaps or a single SVG image can be used.
 
 
+Adapting Existing Code To High DPI  {#high_dpi_existing_code}
+==================================
+
+Generally speaking, adding support for high DPI to the existing wxWidgets
+programs involves doing at least the following:
+
+1. Not using any hard-coded pixel values outside of `FromDIP()` (note that
+   this does _not_ apply to XRC).
+2. Using wxBitmapBundle containing at least 2 (normal and high DPI) bitmaps
+   instead of wxBitmap and wxImageList when setting bitmaps.
+3. Updating any custom art providers to override
+   wxArtProvider::CreateBitmapBundle() (and, of course, return multiple bitmaps
+   from it) instead of wxArtProvider::CreateBitmap().
+4. Removing any calls to wxToolBar::SetToolBitmapSize() or, equivalently,
+   `<bitmapsize>` attributes from the XRC, as this forces unwanted scaling.
+
+
+
 Platform-Specific Build Issues      {#high_dpi_platform_specific}
 ==============================
 
diff --git a/interface/wx/toolbar.h b/interface/wx/toolbar.h
index 8392a2cec7..c021c1ec56 100644
--- a/interface/wx/toolbar.h
+++ b/interface/wx/toolbar.h
@@ -882,6 +882,10 @@ public:
 
         It is usually unnecessary to call this function, as the tools will
         always be made big enough to fit the size of the bitmaps used in them.
+        Moreover, calling it may force wxToolBar to scale its images, even
+        using non-integer scaling factor, which will usually look bad, instead
+        of adapting the image size to the current DPI scaling in order to avoid
+        doing this.
 
         If you do call it, it must be done before toolbar is Realize()'d.
 
@@ -894,6 +898,9 @@ public:
             toolbar->Realize();
         @endcode
 
+        Note that this example would scale bitmaps to 48 pixels when using 150%
+        DPI scaling, which wouldn't happen without calling SetToolBitmapSize().
+
         @param size
             The size of the bitmaps in the toolbar in logical pixels.