Add options: List plugins, and get plugin help.

This fixes the TODO document's notes about not being able to get help
for individual plugins, and about not having any means to list all
loadable plugins.

1 files changed, 30 insertions, 0 deletions

diff --git a/clock/src/lib.rs b/clock/src/lib.rs
index 109045b..76f5ea7 100644
--- a/clock/src/lib.rs
+++ b/clock/src/lib.rs
@@ -159,6 +159,36 @@ impl SwayStatusModule for ClockPlugin {
         let config = ClockConfig::default();
         Box::new(config)
     }
+    fn print_help(&self) {
+        println!(
+r#"Swaystatus Clock plugin.
+
+This plugin is a simple wall clock, implemented as a thin wrapper around the chrono crate (https://github.com/chronotope/chrono). This plugin just has two options: The format of the to-be-printed time, and the update rate.
+
+The general format for a Clock configuration is:
+[Element.Config]
+Format = "<strftime format string>"
+
+[Element.Config.RefreshRate]
+Synchronization = "UtcSynchronized"
+PerThirtyMinutes = <integer>
+
+or alternatively
+[Element.Config]
+Format = "<strftime format string>"
+
+[Element.Config.RefreshRate]
+Synchronization = "NotSynchronized"
+Seconds = <float>
+
+The format is directly passed on to chrono and uses the strftime format. For available formatting options please see https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html or the strftime(3) man page.
+
+For the RefreshRate you can choose between two options. Unless you have a very special use case, you'll likely want to use the UtcSynchronized option. As the name implies this mode aims to update in sync with your computer's system clock. For instance, if you set it to update every second, the text of the clock will update within a few milliseconds after a full second of the system clock passed.
+Since it synchronizes with UTC, and time zones are in general offset by multiples of 30 minutes, 30 minutes has been chosen as maximum time between updates. Following the "make invalid states unrepresentable" paradigm, the actual update rate is set as a fraction of 30 minutes. For example, if you want to update every second, the "PerThirtyMinutes" field needs to be set to 1800. If you need updates every minute, you'll want toset "PerThirtyMinutes" to 30. Beware that setting PerThirtyMinutes above 36000 is not supported.
+
+The other option, "NotSynchronized" is for cases where 30/n minutes as an update rate is not desired. This simply waits approximately Seconds seconds between updates, but does not care about any synchronization to UTC. In other words, if you set this to 24 hours update rate, but launch the program at noon, that's when your date will update instead of midnight. Long story short, this mode only exists because it was easy to implement, and will probably never be useful to anybody."#
+);
+    }
 }
 
 impl ClockPlugin {