Add info about wx.NewIdRef to MigrationGuid, and update OnHTMLOpeningURL section too.

docs/MigrationGuide.rst

@@ -599,11 +599,14 @@ drop the version number from the pip command above.
 wx.html.HtmlWindow.OnOpeningURL
 -------------------------------
 
-In Classic the return value of ``wx.html.HtmlWindow.OnOpeningURL`` could be
+In wxPython Classic the return value of ``wx.html.HtmlWindow.OnOpeningURL`` and
-either a value from the ``wx.html.HtmlOpeningStatus`` enumeration, or a string
+``wx.html.HtmlWindoInterface.OnHTMLOpeningURL`` could be either a value from the
-containing the URL to redirect to. In Phoenix this has been changed to a simpler
+``wx.html.HtmlOpeningStatus`` enumeration, or a string containing the URL to
-wrapper implementation which requires that both an enum value and a string be
+redirect to. 
-returned as a tuple. For example::
+
+In Phoenix this has been changed to a simpler wrapper implementation which
+requires that both an enum value and a string be returned as a tuple. For
+example::
 
     def OnHTMLOpeningURL(self, urlType, url):
         if urlType == wx.html.HTML_URL_IMAGE and url != self.otherURL:
@@ -611,6 +614,32 @@ returned as a tuple. For example::
         return (wx.html.HTML_OPEN, "")
 
 
+wx.NewId is deprecated
+----------------------
+
+:func:`wx.NewId` has been used forever in wxWidgets and wxPython to generate an
+ID for use as the ID for controls, menu items, and similar things. It's really
+quite a stupid implementation however, in that it simply increments a counter
+and returns that value. There is no way for it to check if the ID is already in
+use, for example if the programmer used some static numbers for IDs, or if the
+counter wrapped around the max integer value and started over at the min integer
+value.
+
+So a few years ago the wxWidgets team implemented a reference counting scheme
+for the ID values, and started using it internally. In a more recent release the
+``wx.NewId`` function was deprecated. Then, even more recently, when code
+was added to Phoenix's generator tools to automatically deprecate things that
+are marked as deprecated in wxWidgets, then it became deprecated for us too.
+
+The recommended alternative to ``wx.NewId`` is to just use ``wx.ID_ANY`` when
+creating your widgets or other items with IDs. That will use the reference
+counted ID scheme internally and the ID will be reserved until that item is
+destroyed. In those cases where you would prefer to have items with the same ID,
+or to reuse ID values for some other reason, then you should use the
+:func:`wx.NewIdRef` function instead. It returns a :class:`wx.WindowIDRef`
+object that can be compared with each other, sorted, used as a dictionary key,
+converted to the actual integer value of the ID, etc.
+
 
 .. toctree::
    :maxdepth: 2

etg/utils.py

@@ -92,7 +92,7 @@ def run():
     f.deprecated = """\
 IDs generated by this function can possibly conflict with IDs used elsewhere in
 the application code. It is recommended to instead use the ``wx.ID_ANY`` ID to
-assign generated IDs for the controls menu items and etc. that you create in the
+assign generated IDs for the controls, menu items and etc. that you create in the
 application. These IDs are guaranteed to not conflict with the other IDs that
 are in use in the application. For those cases where you need to create an ID
 that can be used more than once then please see :func:`wx.NewIdRef`.""".replace('\n', ' ')