Add some documentation

Author: segevfiner

README.md

@@ -26,7 +26,7 @@ Arguments:
 Options:
   -d, --display              Keep display on
   -i, --idle                 Keep system from idle sleeping
-  -s, --sleep                Keep system from sleeping (Functionality and conditions for this to work vary by OS)
+  -s, --sleep                Keep system from explicitly sleeping (Functionality and conditions for this to work vary by OS)
       --completions <SHELL>  Generate shell completions [possible values: bash, elvish, fish, powershell, zsh]
   -w <PID>                   Wait for the process with the specified pid to exit. This option is ignored when used with the COMMAND argument
   -h, --help                 Print help information
@@ -66,6 +66,22 @@ See the generated header file for details on the API. See [cargo-c] for futher d
 
 [cargo-c]: https://crates.io/crates/cargo-c
 
+## Technical Details
+|               | Windows                     | macOS                           | Linux                                                       |
+| ------------- | --------------------------- | ------------------------------- | ----------------------------------------------------------- |
+| API           | [`SetThreadExecutionState`] | [`IOPMAssertionCreateWithName`] | [`org.freedesktop.ScreenSaver`] & [systemd Inhibitor Locks] |
+| Debug command | `powercfg /requests`        | `pmset -g assertions`           | `systemd-inhibit --list`, `gnome-session-inhibit --list`    |
+| display       | `ES_DISPLAY_REQUIRED`       | `PreventUserIdleDisplaySleep`   | `org.freedesktop.ScreenSaver.Inhibit`                       |
+| idle          | `ES_SYSTEM_REQUIRED`        | `PreventUserIdleSystemSleep`    | `org.freedesktop.login1.Manager.Inhibit("idle")`            |
+| sleep         | `ES_AWAYMODE_REQUIRED`      | `PreventSystemSleep`            | `org.freedesktop.login1.Manager.Inhibit("sleep")`           |
+
+`idle` prevents the system from going to sleep on an idle timer, while `sleep` tries to prevent the system from going to sleep explicitly by the user (Whether `sleep` also prevents idle sleep varies by OS). `sleep` is restricted and will only work under certain conditions, most notably, the computer must be on AC power (AKA plugged in, not on battery), and is not allowed on Windows on any computer that has modern standby on (Which is unfortunate as modern standby is also used in laptops not only in handheld mobile devices).
+
+[`SetThreadExecutionState`]: https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-setthreadexecutionstate
+[`IOPMAssertionCreateWithName`]: https://developer.apple.com/documentation/iokit/1557134-iopmassertioncreatewithname
+[`org.freedesktop.ScreenSaver`]: https://people.freedesktop.org/~hadess/idle-inhibition-spec/re01.html
+[systemd Inhibitor Locks]: https://www.freedesktop.org/wiki/Software/systemd/inhibit/
+
 ## Notes
 Preventing the computer from explicitly sleeping, and/or by closing the lid, is often restricted in various ways by the OS, e.g. Only on AC power, not in any PC running Windows with [Modern Standby](https://learn.microsoft.com/en-us/windows-hardware/design/device-experiences/modern-standby). Also note that Modern Standby ignores/terminates power requests on DC (Battery) power, [PowerSetRequest - Remarks](https://learn.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-powersetrequest#remarks).
 

src/lib.rs

@@ -63,7 +63,7 @@ struct Options {
     #[builder(default)]
     idle: bool,
 
-    /// Prevent the system from sleeping. Only works under certain, OS dependant, conditions.
+    /// Prevent the system from explicitly sleeping. Only works under certain, OS dependant, conditions.
     #[builder(default)]
     sleep: bool,
 

src/main.rs

@@ -26,7 +26,7 @@ struct Cli {
     #[arg(short, long)]
     idle: bool,
 
-    /// Keep system from sleeping (Functionality and conditions for this to work vary by OS)
+    /// Keep system from explicitly sleeping (Functionality and conditions for this to work vary by OS)
     #[arg(short, long)]
     sleep: bool,
 

src/sys/linux.rs

@@ -4,8 +4,8 @@
 //!
 //! Debug with `systemd-inhibit --list`, `gnome-session-inhibit --list`.
 //!
-//! [ScreenSaver]: https://people.freedesktop.org/~hadess/idle-inhibition-spec/re01.html
-//! [systemd Inhibitor Locks]:(https://www.freedesktop.org/wiki/Software/systemd/inhibit/
+//! [`org.freedesktop.ScreenSaver`]: https://people.freedesktop.org/~hadess/idle-inhibition-spec/re01.html
+//! [systemd Inhibitor Locks]: https://www.freedesktop.org/wiki/Software/systemd/inhibit/
 
 use zbus::{blocking::Connection, proxy};