diff --git a/interface/wx/sizer.h b/interface/wx/sizer.h
index 3aaae6dfbf..2296c39f61 100644
--- a/interface/wx/sizer.h
+++ b/interface/wx/sizer.h
@@ -1647,25 +1647,29 @@ public:
 /**
     @class wxStaticBoxSizer
 
-    wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box around 
+    wxStaticBoxSizer is a sizer derived from wxBoxSizer but adds a static box around
     the sizer.
 
-    The static box may be either created independently or the sizer may create it 
+    The static box may be either created independently or the sizer may create it
     itself as a convenience. In any case, the sizer owns the wxStaticBox control
     and will delete it in the wxStaticBoxSizer destructor.
-    
-    Note that since wxWidgets 2.9.0 you are encouraged to build the windows which are
-    placed inside wxStaticBoxes as children of the wxStaticBox itself:
+
+    Note that since wxWidgets 2.9.1 you are encouraged to create the windows
+    which are added to wxStaticBoxSizer as children of wxStaticBox itself, see
+    this class documentation for more details.
+
+    Example of use of this class:
     @code
-        ...
-        wxStaticBoxSizer *sz = new wxStaticBoxSizer(wxVERTICAL, parentWindow, "StaticBox");
-        sz->Add(new wxStaticText(sz->GetStaticBox(), "This window is a child of the staticbox"));
-        ...
+        void MyFrame::CreateControls()
+        {
+            wxPanel *panel = new wxPanel(this);
+            ...
+            wxStaticBoxSizer *sz = new wxStaticBoxSizer(wxVERTICAL, panel, "Box");
+            sz->Add(new wxStaticText(sz->GetStaticBox(), wxID_ANY,
+                                     "This window is a child of the staticbox"));
+            ...
+        }
     @endcode
-    
-    Creating the windows which are placed inside wxStaticBoxes as siblings of the
-    wxStaticBox is still allowed but it's deprecated as it gives some problems
-    (e.g. relative to tooltips) on some ports.
 
     @library{wxcore}
     @category{winlayout}
diff --git a/interface/wx/statbox.h b/interface/wx/statbox.h
index ff31baeeb4..d2845e4a87 100644
--- a/interface/wx/statbox.h
+++ b/interface/wx/statbox.h
@@ -12,20 +12,33 @@
     A static box is a rectangle drawn around other windows to denote
     a logical grouping of items.
 
-    Note that since wxWidgets 2.9.0 you are encouraged to build the windows which are
-    placed inside wxStaticBoxes as children of the wxStaticBox itself:
-    @code
-        ...
-        wxStaticBox *stbox = new wxStaticBox(parentWindow, wxID_ANY, "StaticBox");
+    Note that while the previous versions required that windows appearing
+    inside a static box be created as its siblings (i.e. use the same parent as
+    the static box itself), since wxWidgets 2.9.1 it is also possible to create
+    them as children of wxStaticBox itself and you are actually encouraged to
+    do it like this if compatibility with the previous versions is not
+    important.
 
-        new wxStaticText(stbox, "This window is a child of the staticbox");
-        ...
+    So the new recommended way to create static box is:
+    @code
+        void MyFrame::CreateControls()
+        {
+            wxPanel *panel = new wxPanel(this);
+            wxStaticBox *box = new wxStaticBox(panel, wxID_ANY, "StaticBox");
+
+            new wxStaticText(box, wxID_ANY "This window is a child of the staticbox");
+            ...
+        }
     @endcode
-    
-    Creating the windows which are placed inside wxStaticBoxes as siblings of the
-    wxStaticBox is still allowed but it's deprecated as it gives some problems
-    (e.g. relative to tooltips) on some ports.
-    
+
+    While the compatible -- and now deprecated -- way is
+    @code
+            wxStaticBox *box = new wxStaticBox(panel, wxID_ANY, "StaticBox");
+
+            new wxStaticText(panel, wxID_ANY "This window is a child of the panel");
+            ...
+    @endcode
+
     Also note that there is a specialized wxSizer class (wxStaticBoxSizer) which can
     be used as an easier way to pack items into a static box.