Document wxSizerItem::Assign{Window,Sizer,Spacer}() methods.

Also explain why SetSpacer() and SetSizer() are deprecated.

Closes #11555.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62944 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/sizer.h

@@ -1017,6 +1017,30 @@ public:
     */
     virtual ~wxSizerItem();
 
+    /**
+        Set the window to be tracked by this item.
+
+        The old window isn't deleted as it is now owned by the sizer item.
+    */
+    void AssignWindow(wxWindow *window);
+
+    /**
+        Set the sizer tracked by this item.
+
+        Old sizer, if any, is deleted.
+    */
+    void AssignSizer(wxSizer *sizer);
+
+    //@{
+    /**
+        Set the size of the spacer tracked by this item.
+
+        Old spacer, if any, is deleted.
+    */
+    void AssignSpacer(const wxSize& size);
+    void AssignSpacer(int w, int h) { AssignSpacer(wxSize(w, h)); }
+    //@}
+
     /**
         Calculates the minimum desired size for the item, including any space
         needed by borders.
@@ -1186,13 +1210,17 @@ public:
 
     /**
         Set the sizer tracked by this item.
-        @deprecated @todo provide deprecation description
+
+        @deprecated This function does not free the old sizer which may result
+        in memory leaks, use AssignSizer() which does free it instead.
     */
     void SetSizer(wxSizer* sizer);
 
     /**
         Set the size of the spacer tracked by this item.
-        @deprecated @todo provide deprecation description
+
+        @deprecated This function does not free the old spacer which may result
+        in memory leaks, use AssignSpacer() which does free it instead.
     */
     void SetSpacer(const wxSize& size);