# HG changeset patch # User Floris Bruynooghe # Date 1603648086 -3600 # Sun Oct 25 18:48:06 2020 +0100 # Node ID 924f95b84a314ed795ef08ed2cea00ecffb9f9d1 # Parent 148f5d0739833f96f77435757f4d61c1bda56f1b Modern doc comments diff --git a/src/dbus.rs b/src/dbus.rs --- a/src/dbus.rs +++ b/src/dbus.rs @@ -1,32 +1,32 @@ -// D-Bus support -// -// The D-Bus service we create is registered under the bus name -// `be.devork.dbus.bright`. -// -// There are two interfaces which exist: -// -// 1. be.devork.dbus.bright.Manager -// methods: -// GetDevices(out ARRAY devices) -// Term() Gracefully shut down the daemon (internal use) -// -// The object having this interface is at -// /be/devork/dbus/bright/manager. -// -// 2. be.devork.dbus.bright.BacklightDevice -// properties: -// Name(STRING) (ro) The name of the device -// Brightness(UNIT32) [rw] The current brightness as a percentage -// MaxBrightness(UINT32) [ro] The raw value of the maximum brightness -// CurBrightness(UINT32) [rw] The raw value of the current brightness -// -// Properties of this interface will emit the -// org.freedesktop.DBus.Properties.PropertiesChanged signal -// whenever their value changes. -// -// The objects having this interface are at -// /be/devork/dbus/bright/devices/, however you should only -// ever acquire these object paths from the manager. +//! D-Bus support. +//! +//! The D-Bus service we create is registered under the bus name +//! `be.devork.dbus.bright`. +//! +//! There are two interfaces which exist: +//! +//! 1. be.devork.dbus.bright.Manager +//! methods: +//! GetDevices(out ARRAY devices) +//! Term() Gracefully shut down the daemon (internal use) +//! +//! The object having this interface is at +//! /be/devork/dbus/bright/manager. +//! +//! 2. be.devork.dbus.bright.BacklightDevice +//! properties: +//! Name(STRING) (ro) The name of the device +//! Brightness(UNIT32) (rw) The current brightness as a percentage +//! MaxBrightness(UINT32) (ro) The raw value of the maximum brightness +//! CurBrightness(UINT32) (rw) The raw value of the current brightness +//! +//! Properties of this interface will emit the +//! org.freedesktop.DBus.Properties.PropertiesChanged signal +//! whenever their value changes. +//! +//! The objects having this interface are at +//! /be/devork/dbus/bright/devices/, however you should only +//! ever acquire these object paths from the manager. use std::collections::HashMap; use std::rc::Rc; @@ -43,7 +43,7 @@ pub static MANAGER_IFACE: &str = "be.devork.dbus.bright.Manager"; pub static DEVICE_IFACE: &str = "be.devork.dbus.bright.BacklightDevice"; -// The public interface. +/// The public interface. #[derive(Debug)] pub struct DBusService { busname: String, @@ -130,15 +130,15 @@ Ok(self.connection.incoming(timeout_ms)) } - // Handle messages and return after timeout expires. - // - // This is different from incoming() since it will always block - // for the specified timeout, even if messages are sent and - // received earlier. This returns Ok(SvcStatus::Terminated) when - // be.devork.dbus.bright.Manager.Term() was called and .shutdown() - // should be called, in which case the timeout will be ignored and - // the function will return early. Otherwise - // Ok(SvcStatus::Running) is returned. + /// Handles messages and returns after timeout expires. + /// + /// This is different from incoming() since it will always block + /// for the specified timeout, even if messages are sent and + /// received earlier. This returns Ok(SvcStatus::Terminated) when + /// be.devork.dbus.bright.Manager.Term() was called and .shutdown() + /// should be called, in which case the timeout will be ignored and + /// the function will return early. Otherwise + /// Ok(SvcStatus::Running) is returned. pub fn handle_msgs( &mut self, timeout: std::time::Duration, @@ -164,9 +164,10 @@ Ok(SvcStatus::Running) } - // We don't really shut down until the connection object is - // destroyed. This unregisters the name and handles all - // outstanding messages. + /// Shut down the D-Bus service. + /// + /// We don't really shut down until the connection object is destroyed which happens on + /// [Drop]. This only unregisters the name and handles all outstanding messages. pub fn shutdown(&self) -> Result<(), failure::Error> { match self.connection.release_name(BUSNAME) { Ok(action) => info!("Releasing busname {}: {:?}", BUSNAME, action), @@ -218,10 +219,10 @@ } } -// The types for the objects stored in the -// be.devork.dbus.bright.Manager interface +/// The types for the objects stored in the be.devork.dbus.bright.Manager interface. #[derive(Copy, Clone, Default, Debug)] struct ManagerTData; + impl dbus::tree::DataType for ManagerTData { type Tree = (); type ObjectPath = Rc>; @@ -272,10 +273,10 @@ Ok(vec![ret]) } -// The types for the objects stored in the -// be.devork.dbus.bright.BacklightDevice interface +/// The type for the objects stored in the be.devork.dbus.bright.BacklightDevice interface. #[derive(Copy, Clone, Default, Debug)] pub struct DeviceTData; + impl dbus::tree::DataType for DeviceTData { type Tree = (); type ObjectPath = crate::BacklightDevice; @@ -490,9 +491,12 @@ /// A blocking client for the D-Bus service. #[derive(Debug)] pub struct Client<'a> { - conn: dbus::Connection, // Connection to the bus. - peer: dbus::BusName<'a>, // D-Bus address of the peer. - timeout: i32, // Timeout in ms to use for D-Bus calls. + /// Connection to the bus. + conn: dbus::Connection, + /// D-Bus address of the peer. + peer: dbus::BusName<'a>, + /// Timeout in ms to use for D-Bus calls. + timeout: i32, } impl<'a> Client<'a> { @@ -521,7 +525,7 @@ .map_err(|_| failure::err_msg("Failed sending Term() message")) } - /// Ping the peer. + /// Pings the peer. /// /// # Errors /// diff --git a/src/lib.rs b/src/lib.rs --- a/src/lib.rs +++ b/src/lib.rs @@ -22,7 +22,7 @@ Ok(devices) } -// A backlight device, create via BacklightDeviceIter +/// A backlight device, created via [create_devices]. #[derive(Debug, Clone)] pub struct BacklightDevice { path: std::path::PathBuf, @@ -48,7 +48,7 @@ } } - // Return a name for the device + /// Returns a name for the device. pub fn name(&self) -> std::borrow::Cow { self.path .components() @@ -58,21 +58,21 @@ .to_string_lossy() } - // Read and return the max_brightness value + /// Reads and return the max_brightness value. pub fn max_brightness(&self) -> Result { let path = self.path.join("max_brightness"); read_uint(&path) } - // Get the current raw brightness value + /// Gets the current raw brightness value. pub fn get_brightness(&self) -> Result { let path = self.path.join("brightness"); read_uint(&path) } - // Set the raw brightness value - // - // Returns the new brightness. + /// Sets the raw brightness value. + /// + /// Returns the new brightness. pub fn set_brightness(&self, n: u32) -> Result { let path = self.path.join("brightness"); let mut fp = fs::File::create(&path)?; @@ -80,7 +80,7 @@ Ok(n) } - // Get brightness as percentage + /// Gets brightness as percentage. pub fn get(&self) -> Result { let max = self.max_brightness()?; let cur = self.get_brightness()?; @@ -88,9 +88,9 @@ Ok(pct.round() as u32) } - // Set brightness as percentage - // - // Returns the new raw brightness. + /// Sets brightness as percentage. + /// + /// Returns the new raw brightness. pub fn set(&self, n: u32) -> Result { let max = self.max_brightness()?; let raw = match (max as f64 / 100.0 * n as f64).round() as u32 { @@ -100,7 +100,7 @@ self.set_brightness(raw) } - // Increase brightness with percentage + /// Increases brightness with percentage. pub fn incr(&self, n: u32) -> Result { let max = self.max_brightness()?; let cur = self.get_brightness()?; @@ -112,7 +112,7 @@ self.set_brightness(raw) } - // Decrease brightness with percentage + /// Decreases brightness with percentage. pub fn decr(&self, n: u32) -> Result { let max = self.max_brightness()?; let cur = self.get_brightness()?; @@ -125,7 +125,7 @@ } } -// Read the unsinged integer from a /sys file +/// Reads the unsinged integer from a /sys file. fn read_uint(path: &std::path::Path) -> Result { let mut fp = fs::File::open(path)?; let mut contents = String::new(); diff --git a/src/pond.rs b/src/pond.rs --- a/src/pond.rs +++ b/src/pond.rs @@ -1,9 +1,10 @@ -/// A collection of threads to run as a group. -/// -/// The collection of threads, aka the pond, allows waiting for the -/// first thread that terminates and collects the results of the -/// threads. The pond represents the scope of the threads, the pond -/// can not be dropped while any threads are running. +//! A collection of threads to run as a group. +//! +//! The collection of threads, aka the pond, allows waiting for the +//! first thread that terminates and collects the results of the +//! threads. The pond represents the scope of the threads, the pond +//! can not be dropped while any threads are running. + use std::sync::{Arc, Condvar, Mutex}; use std::thread;