@@ 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<OBJECT_PATH> 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/<name>, 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<OBJECT_PATH> 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/<name>, 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_PATH: &str = "/be/dev
 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 @@ impl DBusService {
         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 @@ impl DBusService {
         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 @@ impl DBusService {
     }
 }
 
-// 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<Vec<crate::BacklightDevice>>;

          
@@ 272,10 273,10 @@ fn handle_meth_manager_term(
     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 @@ fn signal_brightness_changes(
 /// 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 @@ impl<'a> Client<'a> {
             .map_err(|_| failure::err_msg("Failed sending Term() message"))
     }
 
-    /// Ping the peer.
+    /// Pings the peer.
     ///
     /// # Errors
     ///

          

@@ 22,7 22,7 @@ pub fn create_devices(only: Vec<String>)
     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 @@ impl BacklightDevice {
         }
     }
 
-    // Return a name for the device
+    /// Returns a name for the device.
     pub fn name(&self) -> std::borrow::Cow<str> {
         self.path
             .components()

          
@@ 58,21 58,21 @@ impl BacklightDevice {
             .to_string_lossy()
     }
 
-    // Read and return the max_brightness value
+    /// Reads and return the max_brightness value.
     pub fn max_brightness(&self) -> Result<u32, failure::Error> {
         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<u32, failure::Error> {
         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<u32, failure::Error> {
         let path = self.path.join("brightness");
         let mut fp = fs::File::create(&path)?;

          
@@ 80,7 80,7 @@ impl BacklightDevice {
         Ok(n)
     }
 
-    // Get brightness as percentage
+    /// Gets brightness as percentage.
     pub fn get(&self) -> Result<u32, failure::Error> {
         let max = self.max_brightness()?;
         let cur = self.get_brightness()?;

          
@@ 88,9 88,9 @@ impl BacklightDevice {
         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<u32, failure::Error> {
         let max = self.max_brightness()?;
         let raw = match (max as f64 / 100.0 * n as f64).round() as u32 {

          
@@ 100,7 100,7 @@ impl BacklightDevice {
         self.set_brightness(raw)
     }
 
-    // Increase brightness with percentage
+    /// Increases brightness with percentage.
     pub fn incr(&self, n: u32) -> Result<u32, failure::Error> {
         let max = self.max_brightness()?;
         let cur = self.get_brightness()?;

          
@@ 112,7 112,7 @@ impl BacklightDevice {
         self.set_brightness(raw)
     }
 
-    // Decrease brightness with percentage
+    /// Decreases brightness with percentage.
     pub fn decr(&self, n: u32) -> Result<u32, failure::Error> {
         let max = self.max_brightness()?;
         let cur = self.get_brightness()?;

          
@@ 125,7 125,7 @@ impl BacklightDevice {
     }
 }
 
-// Read the unsinged integer from a /sys file
+/// Reads the unsinged integer from a /sys file.
 fn read_uint(path: &std::path::Path) -> Result<u32, failure::Error> {
     let mut fp = fs::File::open(path)?;
     let mut contents = String::new();

          

@@ 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;