Extend and improve wxSizer::SetSizeHints() documentation

Notably explicitly mention that the parameter of this method does not
need to be the window using this sizer.

interface/wx/sizer.h

@@ -897,14 +897,34 @@ public:
         This method first calls Fit() and then wxTopLevelWindow::SetSizeHints()
         on the @a window passed to it.
 
-        This only makes sense when @a window is actually a wxTopLevelWindow such
+        This function is only when @a window is actually a wxTopLevelWindow such
         as a wxFrame or a wxDialog, since SetSizeHints only has any effect in these classes.
         It does nothing in normal windows or controls.
 
-        This method is implicitly used by wxWindow::SetSizerAndFit() which is
+        Note that @a window does @e not need to be the window using this sizer
-        commonly invoked in the constructor of a toplevel window itself (see
+        and it is, in fact, common to call this function on the sizer
-        the sample in the description of wxBoxSizer) if the toplevel window is
+        associated with the panel covering the client area of a frame passing
-        resizable.
+        it the frame pointer, as this has the desired effect of adjusting the
+        frame size to the size fitting the panel, e.g.:
+        @code
+        MyFrame::MyFrame(...) : wxFrame(...)
+        {
+            wxPanel* panel = new wxPanel(this);
+            wxSizer* sizer = new wxBoxSizer(wxVERTICAL);
+            sizer->Add(...);
+            sizer->Add(...);
+            panel->SetSizer(sizer);
+
+            // Use the panel sizer to set the initial and minimal size of the
+            // frame to fit its contents.
+            sizer->SetSizeHints(this);
+        }
+        @endcode
+
+        This function is also used by wxWindow::SetSizerAndFit() which is
+        commonly invoked in the constructor of wxDialog-derived classes, which
+        don't need to use an intermediate panel, see the example in @ref
+        overview_sizer_programming_box "wxBoxSizer overview".
     */
     void SetSizeHints(wxWindow* window);