Update on_cleared event docs

Improve docs of the `ON_CLEARED` capability and update other docs to allow distinguishing between expired and programatically closed notifications in the future. Actually adding support for expiring notifications is out-of-scope here.

Author: PhrozenByte

README.md

@@ -89,9 +89,9 @@ async def main() -> None:
             on_replied=lambda text: print("Brutus replied:", text),
         ),
         on_dispatched=lambda: print("Notification showing"),
-        on_cleared=lambda: print("Notification timed out"),
+        on_cleared=lambda: print("Notification closed w/o user interaction"),
         on_clicked=lambda: print("Notification clicked"),
-        on_dismissed=lambda: print("Notification dismissed"),
+        on_dismissed=lambda: print("Notification dismissed by the user"),
         sound=DEFAULT_SOUND,
         timeout=10,
     )

examples/eventloop.py

@@ -34,9 +34,9 @@ async def main() -> None:
             on_replied=lambda text: print(f"Received reply '{text}'"),
         ),
         on_dispatched=lambda: print("Notification is showing now"),
-        on_cleared=lambda: print("Notification timed out"),
+        on_cleared=lambda: print("Notification closed w/o user interaction"),
         on_clicked=lambda: print("Notification was clicked"),
-        on_dismissed=lambda: print("Notification was dismissed"),
+        on_dismissed=lambda: print("Notification was dismissed by the user"),
         sound=DEFAULT_SOUND,
         timeout=10,
     )

examples/synchronous.py

@@ -24,9 +24,9 @@
         on_replied=lambda text: print("Brutus replied:", text),
     ),
     on_dispatched=lambda: print("Notification showing"),
-    on_cleared=lambda: print("Notification timed out"),
+    on_cleared=lambda: print("Notification closed w/o user interaction"),
     on_clicked=lambda: print("Notification clicked"),
-    on_dismissed=lambda: print("Notification dismissed"),
+    on_dismissed=lambda: print("Notification dismissed by user"),
     sound=DEFAULT_SOUND,
     timeout=10,
 )

src/desktop_notifier/common.py

@@ -304,8 +304,9 @@ class Capability(Enum):
     """Supports on-dispatched callbacks"""
 
     ON_CLEARED = auto()
-    """Supports distinguishing between an user closing a notification, and clearing a
-    notification programmatically, and consequently supports on-cleared callbacks"""
+    """Supports on-cleared callbacks, which are called if a notification wasn't
+    cleared by user interaction, but programmatically; platforms not supporting
+    this distinction will call on-dismissed callbacks instead"""
 
     ON_CLICKED = auto()
     """Supports on-clicked callbacks"""

src/desktop_notifier/main.py

@@ -300,7 +300,7 @@ def on_dispatched(self, handler: Callable[[str], Any] | None) -> None:
     def on_cleared(self) -> Callable[[str], Any] | None:
         """
         A method to call when a notification is cleared without user interaction
-        (e.g. after a timeout, or if cleared by another process)
+        (e.g. if cleared by another process)
 
         The method must take the notification identifier as a single argument.