From fe8806a4d5f8adc3d37f85fa7df7763f2c3e196b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Simon=20W=C3=B6rner?= Date: Mon, 10 Jul 2017 15:20:14 +0200 Subject: [PATCH] added rust documentation comments --- kawaii/kawaii-rs/Cargo.toml | 2 +- .../dependencies/emergency-stop/Cargo.toml | 4 +++ .../dependencies/emergency-stop/src/lib.rs | 12 +++++-- .../dependencies/kawaii-rs/Cargo.toml | 4 +++ .../dependencies/kawaii-rs/src/gpio.rs | 32 +++++++++++++++++++ .../dependencies/kawaii-rs/src/lib.rs | 2 +- .../dependencies/kawaii-rs/src/measure.rs | 8 +++++ .../dependencies/ultrasonic-irq/Cargo.toml | 4 +++ .../dependencies/ultrasonic-irq/src/lib.rs | 29 ++++++++++++++--- kawaii/kawaii-rs/src/emergency_stop.rs | 3 ++ kawaii/kawaii-rs/src/measure.rs | 7 +++- kawaii/kawaii-rs/src/ultrasonic_irq.rs | 3 ++ 12 files changed, 100 insertions(+), 10 deletions(-) diff --git a/kawaii/kawaii-rs/Cargo.toml b/kawaii/kawaii-rs/Cargo.toml index e766209..c5575ff 100644 --- a/kawaii/kawaii-rs/Cargo.toml +++ b/kawaii/kawaii-rs/Cargo.toml @@ -4,7 +4,7 @@ version = "0.1.0" authors = ["Simon Wörner "] [lib] -name = "kawaii" +name = "kawaii_api" crate-type = ["staticlib"] [features] diff --git a/kawaii/kawaii-rs/dependencies/emergency-stop/Cargo.toml b/kawaii/kawaii-rs/dependencies/emergency-stop/Cargo.toml index 5e19070..271dc01 100644 --- a/kawaii/kawaii-rs/dependencies/emergency-stop/Cargo.toml +++ b/kawaii/kawaii-rs/dependencies/emergency-stop/Cargo.toml @@ -3,6 +3,10 @@ name = "emergency_stop" version = "0.1.0" authors = ["Simon Wörner "] +[[bin]] +name = "emergency_stop-test" +doc = false + [features] measure = ["kawaii/measure"] diff --git a/kawaii/kawaii-rs/dependencies/emergency-stop/src/lib.rs b/kawaii/kawaii-rs/dependencies/emergency-stop/src/lib.rs index 3a9afe7..e5d21dd 100644 --- a/kawaii/kawaii-rs/dependencies/emergency-stop/src/lib.rs +++ b/kawaii/kawaii-rs/dependencies/emergency-stop/src/lib.rs @@ -18,6 +18,10 @@ pub struct EmergencyStop { } impl EmergencyStop { + /// Constructs a new `EmergencyStop` and starts poll thread. + /// + /// # Parameter + /// - `stop_port` GPIO Port number of emergency stop pin. pub fn new(stop_port: u8) -> std::io::Result { let name = format!("EmergencyStop(port = {})", stop_port); let state = Arc::new(AtomicBool::new(false)); @@ -29,11 +33,12 @@ impl EmergencyStop { .spawn(move || EmergencyStop::thread(&mut port, state_clone))?; Ok(EmergencyStop { - thread: Some(thread), - state: state, - }) + thread: Some(thread), + state: state, + }) } + /// Emergency stop poll thread fn thread(port: &mut AsyncPort, state: Arc) { #[cfg(feature = "measure")] let mut measure = Measure::new(format!("EmergencyStop(port = {})", port.port.number)); @@ -86,6 +91,7 @@ impl EmergencyStop { } impl Drop for EmergencyStop { + /// Set emergency stop and join poll thread. fn drop(&mut self) { self.state.store(true, Ordering::Relaxed); diff --git a/kawaii/kawaii-rs/dependencies/kawaii-rs/Cargo.toml b/kawaii/kawaii-rs/dependencies/kawaii-rs/Cargo.toml index ee55705..83dc41a 100644 --- a/kawaii/kawaii-rs/dependencies/kawaii-rs/Cargo.toml +++ b/kawaii/kawaii-rs/dependencies/kawaii-rs/Cargo.toml @@ -3,6 +3,10 @@ name = "kawaii" version = "0.1.0" authors = ["Simon Wörner "] +[[bin]] +name = "kawaii-test" +doc = false + [features] measure = [] diff --git a/kawaii/kawaii-rs/dependencies/kawaii-rs/src/gpio.rs b/kawaii/kawaii-rs/dependencies/kawaii-rs/src/gpio.rs index dbae7be..9522fe9 100644 --- a/kawaii/kawaii-rs/dependencies/kawaii-rs/src/gpio.rs +++ b/kawaii/kawaii-rs/dependencies/kawaii-rs/src/gpio.rs @@ -133,6 +133,11 @@ impl fmt::Debug for AsyncPort { } impl Port { + /// Constructs a new GPIO `Port`. + /// + /// # Parameter + /// - `number` GPIO Port number of pin. + /// - `direction` GPIO Port direction. pub fn new(number: u8, direction: Direction) -> std::io::Result { let port = Port { number: number, @@ -143,6 +148,7 @@ impl Port { Ok(port) } + /// Init GPIO `Port`: export port and set direction fn init(&self) -> std::io::Result<()> { self.export().ok(); self.set_direction()?; @@ -150,6 +156,7 @@ impl Port { Ok(()) } + /// Drop GPIO `Port`: unexport pub fn drop(&mut self) { self.unexport().ok(); } @@ -159,13 +166,17 @@ impl Port { .write_all(value.as_bytes()) } + + /// Export GPIO `Port` fn export(&self) -> std::io::Result<()> { Port::write_path("/sys/class/gpio/export", self.number.to_string().as_str()) } + /// Unexport GPIO `Port` fn unexport(&self) -> std::io::Result<()> { Port::write_path("/sys/class/gpio/unexport", self.number.to_string().as_str()) } + /// Set GPIO `Port` direction fn set_direction(&self) -> std::io::Result<()> { Port::write_path(format!("/sys/class/gpio/gpio{}/direction", self.number).as_str(), self.direction.as_str()) @@ -173,6 +184,11 @@ impl Port { } impl SyncPort { + /// Constructs a new synchronised GPIO `Port`. + /// + /// # Parameter + /// - `number` GPIO Port number of pin. + /// - `direction` GPIO Port direction. pub fn new(number: u8, direction: Direction) -> std::io::Result { Ok(SyncPort { port: Port::new(number, direction)?, @@ -181,6 +197,7 @@ impl SyncPort { }) } + /// Open GPIO `SyncPort` sysfs file fn open(number: u8, direction: Direction) -> std::io::Result { let path = format!("/sys/class/gpio/gpio{}/value", number); let path = Path::new(path.as_str()); @@ -191,6 +208,7 @@ impl SyncPort { }) } + /// Read from GPIO `SyncPort` sysfs file pub fn read(&mut self) -> std::io::Result { self.file.seek(SeekFrom::Start(0))?; self.file.read_exact(&mut self.buffer)?; @@ -199,12 +217,18 @@ impl SyncPort { "Unrecognized GPIO Value")) } + /// Write to GPIO `SyncPort` sysfs file pub fn write(&mut self, value: Value) -> std::io::Result<()> { self.file.write_all(value.as_str().as_bytes()) } } impl AsyncPort { + /// Constructs a new asynchronous GPIO `Port`. + /// + /// # Parameter + /// - `number` GPIO Port number of pin. + /// - `edge` GPIO Port edge detection setting. pub fn new(number: u8, edge: Edge) -> std::io::Result { let port = Port::new(number, Direction::In)?; let file = AsyncPort::open(number)?; @@ -219,12 +243,15 @@ impl AsyncPort { port.init()?; Ok(port) } + + /// Init GPIO `Port`: set edge detection fn init(&self) -> std::io::Result<()> { self.set_edge()?; Ok(()) } + /// Open GPIO `AsyncPort` sysfs file with posix API fn open(number: u8) -> std::io::Result { nix::fcntl::open(format!("/sys/class/gpio/gpio{}/value", number).as_str(), nix::fcntl::O_RDONLY, @@ -239,10 +266,12 @@ impl AsyncPort { } } + /// Posix poll on sysfs file fn nix_poll(&mut self, timeout: i32) -> nix::Result { nix::poll::poll(&mut self.fds, timeout) } + /// Read from GPIO `AsyncPort` sysfs file with posix poll fn poll_read(&mut self, poll: nix::Result) -> std::io::Result> { let poll = poll.or(Err(Error::new(ErrorKind::Other, "poll failed")))?; @@ -261,12 +290,14 @@ impl AsyncPort { |v| Ok(Some(v))) } + /// Read asynchronous from GPIO `AsyncPort` sysfs file pub fn poll(&mut self, timeout: Option) -> std::io::Result> { let poll = self.nix_poll(Self::get_timeout(timeout)); self.poll_read(poll) } + /// Read asynchronous from GPIO `AsyncPort` sysfs file with measure support (ignore poll time) #[cfg(feature = "measure")] pub fn poll_measure(&mut self, timeout: Option, @@ -281,6 +312,7 @@ impl AsyncPort { self.poll_read(poll) } + /// Set GPIO `Port` edge detection fn set_edge(&self) -> std::io::Result<()> { Port::write_path(format!("/sys/class/gpio/gpio{}/edge", self.port.number).as_str(), self.edge.as_str()) diff --git a/kawaii/kawaii-rs/dependencies/kawaii-rs/src/lib.rs b/kawaii/kawaii-rs/dependencies/kawaii-rs/src/lib.rs index 37d3de6..e569b34 100644 --- a/kawaii/kawaii-rs/dependencies/kawaii-rs/src/lib.rs +++ b/kawaii/kawaii-rs/dependencies/kawaii-rs/src/lib.rs @@ -4,4 +4,4 @@ pub mod gpio; mod measure; #[cfg(feature = "measure")] -pub use measure::Measure; \ No newline at end of file +pub use measure::Measure; diff --git a/kawaii/kawaii-rs/dependencies/kawaii-rs/src/measure.rs b/kawaii/kawaii-rs/dependencies/kawaii-rs/src/measure.rs index 11efd20..aaa1aed 100644 --- a/kawaii/kawaii-rs/dependencies/kawaii-rs/src/measure.rs +++ b/kawaii/kawaii-rs/dependencies/kawaii-rs/src/measure.rs @@ -22,6 +22,10 @@ pub struct Measure { } impl Measure { + /// Constructs a new `Measure`. + /// + /// # Parameter + /// - `name` Name of measured component. pub fn new(name: String) -> Self { Measure { min: u64::max_value(), @@ -33,10 +37,12 @@ impl Measure { } } + /// Start measurement pub fn start(&mut self) { self.last = precise_time_ns(); } + /// Pause measurement pub fn pause(&mut self) { if self.last == 0 { #[cfg(debug_assertions)] @@ -48,6 +54,7 @@ impl Measure { self.time += self.time_diff(); } + /// Stop measurement and calculate time difference pub fn stop(&mut self) { if self.last == 0 { #[cfg(debug_assertions)] @@ -98,6 +105,7 @@ impl Measure { } impl Drop for Measure { + /// Print measure results and write times to file fn drop(&mut self) { println!("{}:\n\tmin: {} ns\n\tmax: {} ns", self.name, diff --git a/kawaii/kawaii-rs/dependencies/ultrasonic-irq/Cargo.toml b/kawaii/kawaii-rs/dependencies/ultrasonic-irq/Cargo.toml index 45f029a..e9b791a 100644 --- a/kawaii/kawaii-rs/dependencies/ultrasonic-irq/Cargo.toml +++ b/kawaii/kawaii-rs/dependencies/ultrasonic-irq/Cargo.toml @@ -3,6 +3,10 @@ name = "ultrasonic_irq" version = "0.1.0" authors = ["kawaii "] +[[bin]] +name = 'ultrasonic_irq-test' +doc = false + [features] measure = ["kawaii/measure"] diff --git a/kawaii/kawaii-rs/dependencies/ultrasonic-irq/src/lib.rs b/kawaii/kawaii-rs/dependencies/ultrasonic-irq/src/lib.rs index aa6db09..7c9adcf 100644 --- a/kawaii/kawaii-rs/dependencies/ultrasonic-irq/src/lib.rs +++ b/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 { 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; diff --git a/kawaii/kawaii-rs/src/emergency_stop.rs b/kawaii/kawaii-rs/src/emergency_stop.rs index 4b254d6..5649173 100644 --- a/kawaii/kawaii-rs/src/emergency_stop.rs +++ b/kawaii/kawaii-rs/src/emergency_stop.rs @@ -6,6 +6,7 @@ use std::mem::transmute; use std::ptr::null_mut; use std::sync::atomic::Ordering; +/// Constructs a new `EmergencyStop` on heap and returns pointer. #[no_mangle] pub extern "C" fn emergency_stop_init(stop: u8) -> *mut EmergencyStop { match EmergencyStop::new(stop) { @@ -14,11 +15,13 @@ pub extern "C" fn emergency_stop_init(stop: u8) -> *mut EmergencyStop { } } +/// Drops a `EmergencyStop` pointer on heap. #[no_mangle] pub extern "C" fn emergency_stop_clean(emergency_stop: *mut EmergencyStop) { let _emergency_stop: Box = unsafe { transmute(emergency_stop) }; } +/// Returns `EmergencyStop` pointer state. #[no_mangle] pub extern "C" fn emergency_stop_get_state(emergency_stop: *mut EmergencyStop) -> bool { let emergency_stop = unsafe { &mut *emergency_stop }; diff --git a/kawaii/kawaii-rs/src/measure.rs b/kawaii/kawaii-rs/src/measure.rs index 0f3b231..3a2813b 100644 --- a/kawaii/kawaii-rs/src/measure.rs +++ b/kawaii/kawaii-rs/src/measure.rs @@ -7,6 +7,7 @@ use std::ptr::null_mut; use std::mem::transmute; use std::os::raw::c_char; +/// Constructs a new `Measure` on heap and returns pointer. #[no_mangle] pub extern "C" fn measure_init(name: *const c_char) -> *mut Measure { if name.is_null() { @@ -21,11 +22,13 @@ pub extern "C" fn measure_init(name: *const c_char) -> *mut Measure { } } +/// Drops a `Measure` pointer on heap. #[no_mangle] pub extern "C" fn measure_clean(measure: *mut Measure) { let _measure: Box = unsafe { transmute(measure) }; } +/// Starts measure on `Measure` pointer. #[no_mangle] pub extern "C" fn measure_start(measure: *mut Measure) { let measure = unsafe { &mut *measure }; @@ -33,6 +36,7 @@ pub extern "C" fn measure_start(measure: *mut Measure) { measure.start(); } +/// Pause measure on `Measure` pointer. #[no_mangle] pub extern "C" fn measure_pause(measure: *mut Measure) { let measure = unsafe { &mut *measure }; @@ -40,9 +44,10 @@ pub extern "C" fn measure_pause(measure: *mut Measure) { measure.pause(); } +/// Stop measure on `Measure` pointer. #[no_mangle] pub extern "C" fn measure_stop(measure: *mut Measure) { let measure = unsafe { &mut *measure }; measure.stop(); -} \ No newline at end of file +} diff --git a/kawaii/kawaii-rs/src/ultrasonic_irq.rs b/kawaii/kawaii-rs/src/ultrasonic_irq.rs index dbf8c37..9747407 100644 --- a/kawaii/kawaii-rs/src/ultrasonic_irq.rs +++ b/kawaii/kawaii-rs/src/ultrasonic_irq.rs @@ -6,6 +6,7 @@ use std::sync::atomic::Ordering; use self::ultrasonic_irq::Ultrasonic; +/// Constructs a new `Ultrasonic` on heap and returns pointer. #[no_mangle] pub extern "C" fn ultrasonic_init(trigger: u8, echo: u8, temperature: u8) -> *mut Ultrasonic { match Ultrasonic::new(trigger, echo, temperature) { @@ -14,11 +15,13 @@ pub extern "C" fn ultrasonic_init(trigger: u8, echo: u8, temperature: u8) -> *mu } } +/// Drops a `Ultrasonic` pointer on heap. #[no_mangle] pub extern "C" fn ultrasonic_clean(ultrasonic: *mut Ultrasonic) { let _ultrasonic: Box = unsafe { transmute(ultrasonic) }; } +/// Returns `Ultrasonic` pointer distance. #[no_mangle] pub extern "C" fn ultrasonic_get_distance(ultrasonic: *mut Ultrasonic) -> u32 { let ultrasonic = unsafe { &mut *ultrasonic };