Improve ID documentation and add more links to it

Better describe various kinds of IDs and advise not to use hard-coded
values of them.

docs/doxygen/overviews/windowids.h

@@ -11,18 +11,36 @@
 
 @tableofcontents
 
-Various controls and other parts of wxWidgets need an ID.  Sometimes the ID may
+When creating a new wxWindow-derived class or adding a menu item, its ID must
-be directly provided by the user or have a predefined value, such as
+be specified. An ID is just a unique (at least locally, i.e. inside the same
-@c wxID_OPEN. Often, however, the value of the ID is unimportant and in this
+top level window) integer allowing to find the window or menu item later and to
-case it is enough to use @c wxID_ANY as the ID of an object which tells
+distinguish between events from different objects.
-wxWidgets to assign an ID automatically. All such automatically-assigned IDs
+
-are negative, so the IDs predefined in the user code should always be positive
+If applicable, stock IDs such as ::wxID_EXIT (for menu item) or ::wxID_OK (for
-to avoid clashes with them.
+a button) should be used, see @ref page_stockitems for the full list of such
+IDs.
+
+If the value of an ID is not important, ::wxID_ANY should be used, telling
+wxWidgets to allocate a unique ID automatically. All such
+automatically-assigned IDs are negative and so won't conflict with any
+user-defined IDs as long as they are positive.
 
 If you do care about the ID value but don't want to specify it as a literal in
 your code, you can use wxWindow::NewControlId() to create an ID that had never
-been returned by this function before and, being also negative, never conflicts
+been returned by this function before. Such IDs are also negative.
-with any IDs explicitly defined in the program if the advice above is followed.
+
+Finally, you can just define your own IDs. Typically this is done by using a
+C++ enum to automatically ensure their uniqueness. If you do this, please note
+that your custom IDs must be positive to avoid clashes with the automatically
+assigned IDs discussed above and should @e not have values 0 or 1, that can
+result in surprising behaviour under some platforms. Finally, you also need to
+avoid defining IDs in the range from ::wxID_LOWEST to ::wxID_HIGHEST which is
+reserved for wxWidgets-defined IDs, see ::wxStandardID for more details.
+
+To avoid all these restrictions, it is best to avoid using hard-coded IDs at
+all, they are not needed when using wxEvtHandler::Bind() for event handling
+(unlike with the previously used event tables).
+
 
 @see wxIdManager, wxWindow::NewControlId(), wxWindow::UnreserveControlId()
 

interface/wx/menu.h

@@ -546,6 +546,8 @@ public:
 
         @param id
             The menu command identifier.
+            See @ref overview_windowids for more information about IDs (same
+            considerations apply to both window and menu item IDs).
         @param item
             The string to appear on the menu item.
             See wxMenuItem::SetItemLabel() for more details.

interface/wx/window.h

@@ -358,6 +358,7 @@ public:
             Pointer to a parent window.
         @param id
             Window identifier. If wxID_ANY, will automatically create an identifier.
+            See @ref overview_windowids for more information about IDs.
         @param pos
             Window position. wxDefaultPosition indicates that wxWidgets
             should generate a default position for the window.