diff --git a/interface/wx/dcclient.h b/interface/wx/dcclient.h
index d48807db0d..4777da851b 100644
--- a/interface/wx/dcclient.h
+++ b/interface/wx/dcclient.h
@@ -18,12 +18,6 @@
     automatically sets the clipping area to the damaged area of the window.
     Attempts to draw outside this area do not appear.
 
-    To draw on a window from outside your EVT_PAINT() handler, construct a
-    wxClientDC object.
-
-    To draw on the whole window including decorations, construct a wxWindowDC
-    object (Windows only).
-
     A wxPaintDC object is initialized to use the same font and colours as the
     window it is associated with.
 
@@ -46,16 +40,36 @@ public:
 /**
     @class wxClientDC
 
-    A wxClientDC must be constructed if an application wishes to paint on the
-    client area of a window from outside an EVT_PAINT() handler. This should
-    normally be constructed as a temporary stack object; don't store a
-    wxClientDC object.
+    wxClientDC is primarily useful for obtaining information about the window
+    from outside EVT_PAINT() handler.
 
-    To draw on a window from within an EVT_PAINT() handler, construct a
-    wxPaintDC object instead.
+    Typical use of this class is to obtain the extent of some text string in
+    order to allocate enough size for a window, e.g.
+    @code
+        // Create the initially empty label with the size big enough to show
+        // the given string.
+        wxClientDC dc(this);
+        wxStaticText* text = new wxStaticText
+            (
+                this, wxID_ANY, "",
+                wxPoint(),
+                dc.GetTextExtent("String of max length"),
+                wxST_NO_AUTORESIZE
+            );
+    }
+    @endcode
 
-    To draw on the whole window including decorations, construct a wxWindowDC
-    object (Windows only).
+    @note While wxClientDC may also be used for drawing on the client area of a
+    window from outside an EVT_PAINT() handler in some ports, this does @em not
+    work on all platforms (neither wxOSX nor wxGTK with GTK 3 Wayland backend
+    support this, so drawing using wxClientDC simply doesn't have any effect
+    there) and the only portable way of drawing is via wxPaintDC. To redraw a
+    small part of the window, use wxWindow::RefreshRect() to invalidate just
+    this part and check wxWindow::GetUpdateRegion() in the paint event handler
+    to redraw this part only.
+
+    wxClientDC objects should normally be constructed as temporary stack
+    objects, i.e. don't store a wxClientDC object.
 
     A wxClientDC object is initialized to use the same font and colours as the
     window it is associated with.