Update some window function documentation

Updates some documentation to correspond with changes made since it was originally written, clarifies some function behavior, and includes some assorted typo fixes.

include/SDL3/SDL_events.h

@@ -133,7 +133,7 @@ typedef enum SDL_EventType
     SDL_EVENT_WINDOW_ENTER_FULLSCREEN,  /**< The window has entered fullscreen mode */
     SDL_EVENT_WINDOW_LEAVE_FULLSCREEN,  /**< The window has left fullscreen mode */
     SDL_EVENT_WINDOW_DESTROYED,         /**< The window with the associated ID is being or has been destroyed. If this message is being handled
-                                             in an event watcher, the window handle is still valid and can still be used to retrieve any userdata
+                                             in an event watcher, the window handle is still valid and can still be used to retrieve any properties
                                              associated with the window. Otherwise, the handle has already been destroyed and all resources
                                              associated with it are invalid */
     SDL_EVENT_WINDOW_HDR_STATE_CHANGED, /**< Window HDR properties have changed */
@@ -554,7 +554,7 @@ typedef struct SDL_JoyDeviceEvent
 } SDL_JoyDeviceEvent;
 
 /**
- * Joysick battery level change event structure (event.jbattery.*)
+ * Joystick battery level change event structure (event.jbattery.*)
  *
  * \since This struct is available since SDL 3.0.0.
  */

include/SDL3/SDL_video.h

@@ -971,37 +971,42 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, int
 /**
  * Create a child popup window of the specified parent window.
  *
- * 'flags' **must** contain exactly one of the following: -
- * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any
- * input events. - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu.
- * The topmost popup menu will implicitly gain the keyboard focus.
+ * The flags parameter **must** contain at least one of the following:
+ *
+ * - `SDL_WINDOW_TOOLTIP`: The popup window is a tooltip and will not pass any
+ *   input events.
+ * - `SDL_WINDOW_POPUP_MENU`: The popup window is a popup menu.
+ *   The topmost popup menu will implicitly gain the keyboard focus.
  *
  * The following flags are not relevant to popup window creation and will be
  * ignored:
  *
- * - 'SDL_WINDOW_MINIMIZED'
- * - 'SDL_WINDOW_MAXIMIZED'
- * - 'SDL_WINDOW_FULLSCREEN'
- * - 'SDL_WINDOW_BORDERLESS'
+ * - `SDL_WINDOW_MINIMIZED`
+ * - `SDL_WINDOW_MAXIMIZED`
+ * - `SDL_WINDOW_FULLSCREEN`
+ * - `SDL_WINDOW_BORDERLESS`
+ *
+ * The following flags are incompatible with popup window creation and will cause
+ * it to fail:
+ *
+ * - `SDL_WINDOW_UTILITY`
+ * - `SDL_WINDOW_MODAL`
  *
  * The parent parameter **must** be non-null and a valid window. The parent of
  * a popup window can be either a regular, toplevel window, or another popup
  * window.
  *
  * Popup windows cannot be minimized, maximized, made fullscreen, raised,
- * flash, be made a modal window, be the parent of a modal window, or grab the
+ * flash, be made a modal window, be the parent of a toplevel window, or grab the
  * mouse and/or keyboard. Attempts to do so will fail.
  *
  * Popup windows implicitly do not have a border/decorations and do not appear
  * on the taskbar/dock or in lists of windows such as alt-tab menus.
  *
- * If a parent window is hidden, any child popup windows will be recursively
- * hidden as well. Child popup windows not explicitly hidden will be restored
+ * If a parent window is hidden or destroyed, any child popup windows will be recursively
+ * hidden or destroyed as well. Child popup windows not explicitly hidden will be restored
  * when the parent is shown.
  *
- * If the parent window is destroyed, any child popup windows will be
- * recursively destroyed as well.
- *
  * \param parent the parent of the window, must not be NULL.
  * \param offset_x the x position of the popup window relative to the origin
  *                 of the parent.
@@ -1057,7 +1062,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
  * - `SDL_PROP_WINDOW_CREATE_OPENGL_BOOLEAN`: true if the window will be used
  *   with OpenGL rendering
  * - `SDL_PROP_WINDOW_CREATE_PARENT_POINTER`: an SDL_Window that will be the
- *   parent of this window, required for windows with the "toolip", "menu",
+ *   parent of this window, required for windows with the "tooltip", "menu",
  *   and "modal" properties
  * - `SDL_PROP_WINDOW_CREATE_RESIZABLE_BOOLEAN`: true if the window should be
  *   resizable
@@ -1094,8 +1099,9 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_CreatePopupWindow(SDL_Window *paren
  *   [README/wayland](README/wayland) for more information on using custom
  *   surfaces.
  * - `SDL_PROP_WINDOW_CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN` - true if the
- *   application wants an associated `wl_egl_window` object to be created,
- *   even if the window does not have the OpenGL property or flag set.
+ *   application wants an associated `wl_egl_window` object to be created and
+ *   attached to the window, even if the window does not have the OpenGL property
+ *   or `SDL_WINDOW_OPENGL` flag set.
  * - `SDL_PROP_WINDOW_CREATE_WAYLAND_WL_SURFACE_POINTER` - the wl_surface
  *   associated with the window, if you want to wrap an existing window. See
  *   [README/wayland](README/wayland) for more information.
@@ -1251,7 +1257,7 @@ extern SDL_DECLSPEC SDL_Window * SDLCALL SDL_GetWindowParent(SDL_Window *window)
  * - `SDL_PROP_WINDOW_UIKIT_WINDOW_POINTER`: the `(__unsafe_unretained)`
  *   UIWindow associated with the window
  * - `SDL_PROP_WINDOW_UIKIT_METAL_VIEW_TAG_NUMBER`: the NSInteger tag
- *   assocated with metal views on the window
+ *   associated with metal views on the window
  * - `SDL_PROP_WINDOW_UIKIT_OPENGL_FRAMEBUFFER_NUMBER`: the OpenGL view's
  *   framebuffer object. It must be bound when rendering to the screen using
  *   OpenGL.
@@ -1561,7 +1567,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, i
  * Some devices have portions of the screen which are partially obscured or
  * not interactive, possibly due to on-screen controls, curved edges, camera
  * notches, TV overscan, etc. This function provides the area of the window
- * which is safe to have interactible content. You should continue rendering
+ * which is safe to have interactable content. You should continue rendering
  * into the rest of the window, but it should not contain visually important
  * or interactible content.
  *
@@ -2293,9 +2299,15 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *window);
  * reparented to the new owner. Setting the parent window to NULL unparents
  * the window and removes child window status.
  *
+ * If a parent window is hidden or destroyed, the operation will be recursively
+ * applied to child windows. Child windows hidden with the parent that did not
+ * have their hidden status explicitly set will be restored when the parent is shown.
+ *
  * Attempting to set the parent of a window that is currently in the modal
- * state will fail. Use SDL_SetWindowModalFor() to cancel the modal status
- * before attempting to change the parent.
+ * state will fail. Use SDL_SetWindowModal() to cancel the modal status before attempting
+ * to change the parent.
+ *
+ * Popup windows cannot change parents and attempts to do so will fail.
  *
  * Setting a parent window that is currently the sibling or descendent of the
  * child window results in undefined behavior.
@@ -2480,8 +2492,7 @@ extern SDL_DECLSPEC bool SDLCALL SDL_FlashWindow(SDL_Window *window, SDL_FlashOp
 /**
  * Destroy a window.
  *
- * Any popups or modal windows owned by the window will be recursively
- * destroyed as well.
+ * Any child windows owned by the window will be recursively destroyed as well.
  *
  * \param window the window to destroy.
  *