don't expose dbus internals, docs

client/Cargo.toml

@@ -1,11 +1,12 @@
 [package]
 name = "shortcutd"
-version = "0.1.0"
+version = "0.2.0"
 authors = ["Robin Appelman <robin@icewind.nl>"]
 edition = "2021"
 description = "shortcutd client library"
 license = "MIT OR Apache-2.0"
 repository = "https://github.com/icewind1991/shortcutd"
+readme = "../README.md"
 
 [lib]
 name = "shortcutd"
@@ -14,7 +15,7 @@ path = "src/lib.rs"
 [dependencies]
 futures = "0.3.28"
 zbus = { version = "3.13.1", features = ["tokio"], default-features = false }
-evdev-shortcut = { version = "0.1.2", default_features = false }
+evdev-shortcut = { version = "0.1.4", default_features = false }
 
 [dev-dependencies]
 test-case = "3.1.0"

client/examples/client.rs

@@ -24,7 +24,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     pin_mut!(stream);
 
     while let Some(event) = stream.next().await {
-        println!("{} {}", event.shortcut, event.state.as_str());
+        println!("{} {}", event.shortcut, event.state);
     }
     Ok(())
 }

client/examples/simple.rs

@@ -13,7 +13,7 @@ async fn main() -> Result<(), Box<dyn Error>> {
     pin_mut!(stream);
 
     while let Some(event) = stream.next().await {
-        println!("{} {}", event.shortcut, event.state.as_str());
+        println!("{} {}", event.shortcut, event.state);
     }
     Ok(())
 }

client/src/dbus.rs

@@ -0,0 +1,20 @@
+use zbus::dbus_proxy;
+use zbus::fdo;
+
+#[dbus_proxy(
+    interface = "nl.icewind.shortcutd",
+    default_service = "nl.icewind.shortcutd",
+    default_path = "/register"
+)]
+trait Register {
+    async fn register(&self, shortcut: &str) -> fdo::Result<String>;
+}
+
+#[dbus_proxy(
+    interface = "nl.icewind.shortcutd",
+    default_service = "nl.icewind.shortcutd"
+)]
+trait ShortcutSignal {
+    #[dbus_proxy(signal)]
+    async fn triggered(&self, pressed: bool) -> fdo::Result<()>;
+}

client/src/lib.rs

@@ -1,42 +1,64 @@
+//! shortcutd is a daemon and client library to allow listening for global shortcuts for systems that don't support it
+//! otherwise (such as wayland).
+//!
+//! The shortcutd daemon hooks into the evdev system and exposes a dbus interface for clients to hook into to.
+//! By separating out the code that hooks into evdev (which needs to be done as root) into a separate daemon
+//! it allows non-privileged users to hook into global shortcuts.
+//!
+//! Protection against clients using the shortcutd daemon for a keylogger is done by only allowing 3 shortcuts without modifiers to be registered at the same time.
+//!
+//! See the [README](https://github.com/icewind1991/shortcutd) for instruction to running the shortcut daemon.
+//!
+//! Example:
+//!
+//! ```rust,no_run
+//! # use futures::{pin_mut, StreamExt};
+//! # use shortcutd::{Shortcut, ShortcutClient};
+//! # use std::error::Error;
+//! # #[tokio::main]
+//! # async fn main() -> Result<(), Box<dyn Error>> {
+//! let client = ShortcutClient::new().await?;
+//! let shortcut: Shortcut = "<Ctrl><Alt>-KeyO".parse()?;
+//!
+//! let stream = client.listen(shortcut).await?;
+//! pin_mut!(stream);
+//!
+//! while let Some(event) = stream.next().await {
+//!     println!("{} {}", event.shortcut, event.state);
+//! }
+//! # Ok(())
+//! # }
+//! ```
+//!
+
+mod dbus;
+
+use dbus::{RegisterProxy, ShortcutSignalProxy};
 pub use evdev_shortcut::{Key, Modifier, ModifierList, Shortcut, ShortcutEvent, ShortcutState};
 use futures::Stream;
 use futures::StreamExt;
-use zbus::dbus_proxy;
-use zbus::{fdo, Connection};
-
-#[dbus_proxy(
-    interface = "nl.icewind.shortcutd",
-    default_service = "nl.icewind.shortcutd",
-    default_path = "/register"
-)]
-trait Register {
-    async fn register(&self, shortcut: &str) -> fdo::Result<String>;
-}
-
-#[dbus_proxy(
-    interface = "nl.icewind.shortcutd",
-    default_service = "nl.icewind.shortcutd"
-)]
-trait ShortcutSignal {
-    #[dbus_proxy(signal)]
-    async fn triggered(&self, pressed: bool) -> fdo::Result<()>;
-}
+use zbus::Connection;
 
 pub struct ShortcutClient {
     connection: Connection,
 }
 
 impl ShortcutClient {
+    /// Create a new client by connecting to the system dbus
     pub async fn new() -> Result<Self, zbus::Error> {
         Ok(ShortcutClient {
             connection: Connection::system().await?,
         })
     }
 
+    /// Create a client from an existing dbus connection
     pub fn from_zbus(connection: Connection) -> Self {
         ShortcutClient { connection }
     }
 
+    /// Listen to a shortcut
+    ///
+    /// Returns a stream of of shortcut events
     pub async fn listen(
         &self,
         shortcut: Shortcut,