Python: Add some API docs for timer, timermode, and the loader

api/python/slint/__init__.py

@@ -347,6 +347,22 @@ class SlintAutoLoader:
 
 
 loader = SlintAutoLoader()
+"""The `loader` object is a global object that can be used to load Slint files from the file system. It exposes two stages of attributes:
+1. Any lookup of an attribute in the loader will try to match a file in `sys.path` with the `.slint` extension. For example `loader.my_component` will look for a file `my_component.slint` in the directories in `sys.path`.
+2. Any lookup in the object returned by the first stage will try to match an exported component in the loaded file, or a struct or enum. For example `loader.my_component.MyComponent` will look for an *exported* component named `MyComponent` in the file `my_component.slint`.
+
+Note that the first entry in the module search path `sys.path` is the directory that contains the input script.
+
+Example:
+```python
+import slint
+# Look for a file `main.slint` in the current directory,
+# #load & compile it, and instantiate the exported `MainWindow` component
+main_window = slint.loader.main_window.MainWindow()
+main_window.show()
+...
+```
+"""
 
 
 def _callback_decorator(

api/python/slint/slint.pyi

@@ -86,6 +86,8 @@ class TimerMode(Enum):
     Repeated = auto()
 
 class Timer:
+    running: bool
+    interval: datetime.timedelta
     def __new__(
         cls,
     ) -> "Timer": ...
@@ -96,8 +98,6 @@ class Timer:
     def single_shot(duration: datetime.timedelta, callback: typing.Any) -> None: ...
     def stop(self) -> None: ...
     def restart(self) -> None: ...
-    def running(self) -> bool: ...
-    def set_interval(self, interval: datetime.timedelta) -> None: ...
 
 def set_xdg_app_id(app_id: str) -> None: ...
 def run_event_loop() -> None: ...

api/python/timer.rs

@@ -6,6 +6,9 @@ use pyo3_stub_gen::{
     derive::gen_stub_pyclass, derive::gen_stub_pyclass_enum, derive::gen_stub_pymethods,
 };
 
+/// The TimerMode specifies what should happen after the timer fired.
+///
+/// Used by the `Timer.start()` function.
 #[derive(Copy, Clone)]
 #[gen_stub_pyclass_enum]
 #[pyclass(name = "TimerMode")]
@@ -25,6 +28,18 @@ impl From<PyTimerMode> for i_slint_core::timers::TimerMode {
     }
 }
 
+/// Timer is a handle to the timer system that allows triggering a callback to be called
+/// after a specified period of time.
+///
+/// Use `Timer.start()` to create a timer that can repeat at frequent interval, or
+/// `Timer.single_shot()` if you just want to call a function with a delay and do not
+/// need to be able to stop it.
+///
+/// The timer will automatically stop when garbage collected. You must keep the Timer object
+/// around for as long as you want the timer to keep firing.
+///
+/// The timer can only be used in the thread that runs the Slint event loop.
+/// They will not fire if used in another thread.
 #[gen_stub_pyclass]
 #[pyclass(name = "Timer", unsendable)]
 pub struct PyTimer {
@@ -39,6 +54,14 @@ impl PyTimer {
         PyTimer { timer: Default::default() }
     }
 
+    /// Starts the timer with the given mode and interval, in order for the callback to called when the
+    /// timer fires. If the timer has been started previously and not fired yet, then it will be restarted.
+    ///
+    /// Arguments:
+    /// * `mode`: The timer mode to apply, i.e. whether to repeatedly fire the timer or just once.
+    /// * `interval`: The duration from now until when the timer should fire. And the period of that timer
+    ///    for `TimerMode.Repeated` timers.
+    /// * `callback`: The function to call when the time has been reached or exceeded.
     fn start(
         &self,
         mode: PyTimerMode,
@@ -56,6 +79,12 @@ impl PyTimer {
         Ok(())
     }
 
+    /// Starts the timer with the duration, in order for the callback to called when the
+    /// timer fires. It is fired only once and then deleted.
+    ///
+    /// Arguments:
+    /// * `duration`: The duration from now until when the timer should fire.
+    /// * `callback`: The function to call when the time has been reached or exceeded.
     #[staticmethod]
     fn single_shot(duration: chrono::Duration, callback: PyObject) -> PyResult<()> {
         let duration = duration
@@ -69,18 +98,32 @@ impl PyTimer {
         Ok(())
     }
 
+    /// Stops the previously started timer. Does nothing if the timer has never been started.
     fn stop(&self) {
         self.timer.stop();
     }
 
+    /// Restarts the timer. If the timer was previously started by calling `Timer.start()`
+    /// with a duration and callback, then the time when the callback will be next invoked
+    /// is re-calculated to be in the specified duration relative to when this function is called.
+    ///
+    /// Does nothing if the timer was never started.
     fn restart(&self) {
         self.timer.restart();
     }
 
+    /// Set to true if the timer is running; false otherwise.
+    #[getter]
     fn running(&self) -> bool {
         self.timer.running()
     }
 
+    /// The duration of timer.
+    ///
+    /// When setting this property and the timer is running (see `Timer.running`),
+    /// then the time when the callback will be next invoked is re-calculated to be in the
+    /// specified duration relative to when this property is set.
+    #[setter]
     fn set_interval(&self, interval: chrono::Duration) -> PyResult<()> {
         let interval = interval
             .to_std()
@@ -88,4 +131,9 @@ impl PyTimer {
         self.timer.set_interval(interval);
         Ok(())
     }
+
+    #[getter]
+    fn interval(&self) -> core::time::Duration {
+        self.timer.interval()
+    }
 }