Improvements to docs, including a prototype custom event loop.

Doc/library/asyncio-eventloop.rst

@@ -215,36 +215,48 @@ Running and stopping the loop
    Set up an event loop so that it is ready to start actively looping and
    processing events.
 
-   Returns the state that must be restored when the loop concludes. This state
-   should be passed in as arguments to :meth:`loop.run_forever_cleanup()`.
-
    .. note::
 
-      This method is only needed if you are writing your own ``EventLoop``
-      subclass, with a customized inner event processing loop. For example, if
-      you are integrating Python's asyncio event loop with a GUI library's event
-      loop, you can use this method to ensure that Python's event loop is
-      correctly configured and ready to start processing individual events. Most
-      end users will not need to use this method directly.
+      End users should not use this method directly. This method is only needed
+      if you are writing your own ``EventLoop`` subclass, with a customized
+      event processing loop. For example, if you are integrating Python's
+      asyncio event loop with a GUI library's event loop, you may need to write
+      a customized :meth:`loop.run_forever` implementation that accommodates
+      both CPython's event loop and the GUI library's event loop. You can use
+      this method to ensure that Python's event loop is correctly configured and
+      ready to start processing events.
+
+      The specific details of a customized ``EventLoop`` subclass will depend
+      on the GUI library you are integrating with. However, the broad structure
+      of a custom ``EventLoop`` would look something like::
+
+         class CustomGUIEventLoop(EventLoop):
+            def run_forever(self):
+               try:
+                  self.run_forever_setup()
+                  gui_library.setup()
+                  while True:
+                     self._run_once()
+                     gui_library.process_events()
+                     if self._stopping:
+                        break
+               finally:
+                  self.run_forever_cleanup()
+                  gui_library.cleanup()
 
    .. versionadded:: 3.13
 
-.. method:: loop.run_forever_cleanup(original_state)
+.. method:: loop.run_forever_cleanup()
 
    Perform any cleanup necessary at the conclusion of event processing to ensure
    that the event loop has been fully shut down.
 
-   The *original_state* argument is the return value provided by the call to
-   :meth:`loop.run_forever_setup()` that was used to set up the event loop.
-
    .. note::
 
-      This method is only needed if you are writing your own ``EventLoop``
-      subclass, with a customized inner event processing loop. For example, if
-      you are integrating Python's asyncio event loop with a GUI library's event
-      loop, you can use this method to ensure that Python's event loop has been
-      fully shut down at the conclusion of processing events. Most end users
-      will not need to use this method directly.
+      End users should not use this method directly. This method is only needed
+      if you are writing your own ``EventLoop`` subclass, with a customized
+      inner event processing loop. See :meth:`loop.run_forever_setup()` for
+      details on why and how to use this method.
 
    .. versionadded:: 3.13