Document with sphinx timed_events, common, and add methods to PluginAPI

- add methods related to timed events to the PluginAPI
- remove parse_command_args_to_alias because str.format does that, and
  better
→ update the alias plugin

1 files changed, 35 insertions, 8 deletions

diff --git a/src/timed_events.py b/src/timed_events.py
index 5be2aba2..a922ee03 100644
--- a/src/timed_events.py
+++ b/src/timed_events.py
@@ -6,8 +6,11 @@
 # it under the terms of the zlib license. See the COPYING file.
 
 """
-To use these, just use core.add_timed_event(event)
-where event is an instance of one of these classes
+Timed events are the standard way to schedule events for later in poezio.
+
+Once created, they must be added to the list of checked events with
+:py:func:`Core.add_timed_event` (within poezio) or with
+:py:func:`.PluginAPI.add_timed_event` (within a plugin).
 """
 
 import logging
@@ -18,13 +21,22 @@ import datetime
 
 class TimedEvent(object):
     """
-    An event with a callback that is called when the specified time is passed
+    An event with a callback that is called when the specified time is passed.
+
     Note that these events can NOT be used for very small delay or a very
     precise date, since the check for events is done once per second, as
     a maximum.
+
     The callback and its arguments should be passed as the lasts arguments.
     """
     def __init__(self, date, callback, *args):
+        """
+        Create a new timed event.
+
+        :param datetime.datetime date: Time at which the callback must be run.
+        :param function callback: The handler that will be executed.
+        :param \*args: Optional arguments passed to the handler.
+        """
         self._callback = callback
         self.args = args
         self.repetive = False
@@ -42,7 +54,11 @@ class TimedEvent(object):
 
     def has_timed_out(self, current_date):
         """
-        returns True if the callback should be called
+        Check if the event has timed out.
+
+        :param datetime.datetime current_date: The current date.
+        :returns: True if the callback should be called
+        :rtype: bool
         """
         if self.next_call_date < current_date:
             return True
@@ -51,22 +67,33 @@ class TimedEvent(object):
 
     def change_date(self, date):
         """
-        Simply change the date of the event
+        Simply change the date of the event.
+
+        :param datetime.datetime date: Next date.
         """
         self.next_call_date = date
 
     def add_delay(self, delay):
         """
-        Add a delay (in seconds) to the date
+        Add a delay (in seconds) to the date.
+
+        :param int delay: The delay to add.
         """
         self.next_call_date += datetime.timedelta(seconds=delay)
 
 class DelayedEvent(TimedEvent):
     """
-    The date is calculated from now + a delay in seconds
-    Use it if you want an event to happen in, e.g. 6 seconds
+    A TimedEvent, but with the date calculated from now + a delay in seconds.
+    Use it if you want an event to happen in, e.g. 6 seconds.
     """
     def __init__(self, delay, callback, *args):
+        """
+        Create a new DelayedEvent.
+
+        :param int delay: The number of seconds.
+        :param function callback: The handler that will be executed.
+        :param \*args: Optional arguments passed to the handler.
+        """
         date = datetime.datetime.now() + datetime.timedelta(seconds=delay)
         TimedEvent.__init__(self, date, callback, *args)