added rust documentation comments

kawaii/kawaii-rs/dependencies/ultrasonic-irq/src/lib.rs

@@ -47,8 +47,20 @@ pub struct Ultrasonic {
 }
 
 impl Ultrasonic {
+    /// Constructs a new `Ultrasonic` and start threads.
+    ///
+    /// # Threads
+    /// - `UltrasonicTrigger`
+    /// - `UltrasonicEcho`
+    ///
+    /// # Parameter
+    /// - `trigger_port` GPIO Port number of trigger pin.
+    /// - `echo_port` GPIO Port number of echo pin.
+    /// - `temperature` Room temperature in °C.
     pub fn new(trigger_port: u8, echo_port: u8, temperature: u8) -> std::io::Result<Ultrasonic> {
         let distance = Arc::new(AtomicU32::new(u32::max_value()));
+
+        /// Create `UltrasonicEcho` thread with sync channel.
         let echo = UltrasonicEcho {
             echo: AsyncPort::new(echo_port, Edge::Both)?,
             temperature: temperature,
@@ -64,6 +76,7 @@ impl Ultrasonic {
             tx: tx,
         };
 
+        /// Create `UltrasonicTrigger` thread with sync channel.
         let trigger = UltrasonicTrigger { trigger: SyncPort::new(trigger_port, Direction::Out)? };
         let (tx, rx): (Sender<()>, Receiver<()>) = mpsc::channel();
         let name = format!("Ultrasonic::trigger(port = {})", trigger_port);
@@ -83,6 +96,7 @@ impl Ultrasonic {
 }
 
 impl Drop for Ultrasonic {
+    /// Drop sync channels and join threads.
     fn drop(&mut self) {
         if let Some(echo) = self.echo.take() {
             echo.tx.send(()).is_ok();
@@ -97,9 +111,11 @@ impl Drop for Ultrasonic {
 }
 
 impl UltrasonicTrigger {
+    /// `UltrasonicTrigger` thread function.
     fn thread(mut self, stop_rx: Receiver<()>) {
         #[cfg(feature = "measure")]
-        let mut measure = Measure::new(format!("Ultrasonic::trigger(port = {})", self.trigger.port.number));
+        let mut measure = Measure::new(format!("Ultrasonic::trigger(port = {})",
+                                               self.trigger.port.number));
 
         while stop_rx.try_recv().is_err() {
             #[cfg(feature = "measure")]
@@ -124,9 +140,11 @@ impl UltrasonicTrigger {
 }
 
 impl UltrasonicEcho {
+    /// `UltrasonicEcho` thread function.
     fn thread(mut self, stop_rx: Receiver<()>) {
         #[cfg(feature = "measure")]
-        let mut measure = Measure::new(format!("Ultrasonic::echo(port = {})", self.echo.port.number));
+        let mut measure = Measure::new(format!("Ultrasonic::echo(port = {})",
+                                               self.echo.port.number));
 
         while stop_rx.try_recv().is_err() {
             #[cfg(feature = "measure")]
@@ -136,7 +154,8 @@ impl UltrasonicEcho {
             let value = self.echo.poll(Some(Duration::new(1, 0)));
 
             #[cfg(feature = "measure")]
-            let value = self.echo.poll_measure(Some(Duration::new(1, 0)), &mut measure);
+            let value = self.echo
+                .poll_measure(Some(Duration::new(1, 0)), &mut measure);
 
             match value {
                 Ok(value) => {
@@ -155,6 +174,7 @@ impl UltrasonicEcho {
         }
     }
 
+    /// Start time measure or calculates distance based on port value
     fn on_value_changed(&mut self, value: Value) {
         match value {
             Value::High => {
@@ -167,7 +187,7 @@ impl UltrasonicEcho {
                     self.calc_distance();
                 }
 
-                self.timestamp = precise_time_ns()
+                self.timestamp = precise_time_ns();
             }
             Value::Low => {
                 // Switched from Value::Low to Value::Low
@@ -181,6 +201,7 @@ impl UltrasonicEcho {
         }
     }
 
+    /// Calculates distance based on time measurement and `temperature` and stores it in `distance`
     fn calc_distance(&mut self) {
         let time_diff = precise_time_ns() - self.timestamp;
         let distance = (3315 + self.temperature as u64 * 6) * time_diff / 20_000_000;