Updated docs.

Author: kmvanbrunt

CHANGELOG.md

@@ -69,8 +69,6 @@ prompt is displayed.
           displaying realtime status information while the prompt is displayed, see the
           `cmd2.Cmd2.get_bottom_toolbar` method that can be overridden as well as the updated
           `getting_started.py` example
-    - Added `cmd2.Cmd._in_prompt` flag that is set to `True` when the prompt is displayed and the
-      application is waiting for user input
     - New `cmd2.Cmd` methods
         - **get_bottom_toolbar**: populates bottom toolbar if `bottom_toolbar` is `True`
         - **get_rprompt**: override to populate right prompt

cmd2/cmd2.py

@@ -286,7 +286,11 @@ class AsyncAlert:
     """Contents of an asynchonous alert which display while user is at prompt.
 
     :param msg: an optional message to be printed above the prompt.
-    :param prompt: an optional string to dynamically replace the current prompt.
+    :param prompt: an optional string to dynamically replace the active prompt.
+
+    :ivar timestamp: monotonic creation time of the alert. If an alert was created
+                     before the active prompt started, the prompt update is ignored
+                     to avoid a stale display but the msg will still be displayed.
     """
 
     msg: str | None = None
@@ -3367,7 +3371,7 @@ def _process_alerts(self) -> None:
                 # Get the next alert while still holding the condition lock.
                 alert = self._alert_queue.get()
 
-            # Only apply prompt changes generated after the current prompt started.
+            # Only apply prompt changes generated after the active prompt started.
             prompt_updated = False
             if (alert.prompt is not None and
                 alert.prompt != self.prompt and
@@ -3376,7 +3380,7 @@ def _process_alerts(self) -> None:
                 prompt_updated = True
 
             if alert.msg:
-                # Print the message above the current prompt.
+                # Print the message above the active prompt.
                 with patch_stdout():
                     print_formatted_text(pt_filter_style(alert.msg))
 
@@ -5313,7 +5317,7 @@ def add_alert(self, *, msg: str | None = None, prompt: str | None = None) -> Non
             add_alert(msg="Done", prompt="> ")    # Update both
 
         :param msg: an optional message to be printed above the prompt.
-        :param prompt: an optional string to dynamically replace the current prompt.
+        :param prompt: an optional string to dynamically replace the active prompt.
 
         """
         if msg is None and prompt is None:

docs/features/prompt.md

@@ -29,14 +29,25 @@ for an example of dynamically updating the prompt.
 ## Asynchronous Feedback
 
 `cmd2` provides a function to deliver asynchronous feedback to the user without interfering with the
-command line. This means the feedback is provided to the user when they are still entering text at
-the prompt.
+command line. This allows feedback to be provided while the user is still entering text at the prompt.
 
 - [cmd2.Cmd.add_alert][]
 
-`cmd2` also provides a function to change the title of the terminal window. This feature requires
-the application be running in a terminal that supports VT100 control characters. Linux, Mac, and
-Windows 10 and greater all support these.
+### Asynchronous Feedback Mechanisms
+
+Alerts can interact with the CLI in two ways:
+
+1. **Message Printing**: It can print a message directly above the current prompt line.
+1. **Prompt Updates**: It can dynamically replace the text of the active prompt to reflect changing
+   state.
+
+> **Note**: To ensure the user interface remains accurate, a prompt update is ignored if the alert
+> was created before the active prompt started. This prevents older alerts from overwriting a newer
+> prompt, though the alert's message will still be printed.
+
+### Terminal Window Management
+
+`cmd2` also provides a function to change the title of the terminal window.
 
 - [cmd2.Cmd.set_window_title][]