From cbcc23e543ef4ccb8315ffd860c73b09a046db8d Mon Sep 17 00:00:00 2001 From: Aron Heinecke Date: Fri, 5 Aug 2022 00:21:25 +0200 Subject: [PATCH] add docs --- notify-debouncer-mini/README.md | 6 ++- notify-debouncer-mini/src/lib.rs | 84 +++++++++++++++++++++++++------- 2 files changed, 71 insertions(+), 19 deletions(-) diff --git a/notify-debouncer-mini/README.md b/notify-debouncer-mini/README.md index f5bbfaa5..5bdb7060 100644 --- a/notify-debouncer-mini/README.md +++ b/notify-debouncer-mini/README.md @@ -1,5 +1,7 @@ # Notify debouncer +[![ยป Docs](https://flat.badgen.net/badge/api/docs.rs/df3600)][docs] + Tiny debouncer for notify. Filters incoming events and emits only one event per timeframe per file. ## Features @@ -7,4 +9,6 @@ Tiny debouncer for notify. Filters incoming events and emits only one event per - `crossbeam` enabled by default, for crossbeam channel support. This may create problems used in tokio environments. See [#380](https://github.com/notify-rs/notify/issues/380). Use someting like `notify-debouncer-mini = { version = "*", default-features = false }` to disable it. -- `serde` for serde support of event types, off by default \ No newline at end of file +- `serde` for serde support of event types, off by default + +[docs]: https://docs.rs/notify/0.1/notify-debouncer-mini/ \ No newline at end of file diff --git a/notify-debouncer-mini/src/lib.rs b/notify-debouncer-mini/src/lib.rs index ced8eeec..bad3a54a 100644 --- a/notify-debouncer-mini/src/lib.rs +++ b/notify-debouncer-mini/src/lib.rs @@ -1,4 +1,43 @@ -//! Debouncer & access code +//! Debouncer for notify +//! +//! # Installation +//! +//! ```toml +//! [dependencies] +//! notify = "5.0.0-pre.15" +//! notify-debouncer-mini = "0.1" +//! ``` +//! +//! # Examples +//! +//! ```rust,no_run +//! # use std::path::Path; +//! # use std::time::Duration; +//! use notify::{Watcher, RecursiveMode, Result}; +//! use notify_debouncer_mini::{new_debouncer,DebounceEventResult}; +//! +//! # fn main() { +//! // Select recommended watcher for debouncer. +//! // Using a callback here, could also be a channel. +//! let mut debouncer = new_debouncer(Duration::from_secs(2), None, |res: DebounceEventResult| { +//! match res { +//! Ok(events) => events.iter().for_each(|e|println!("Event {:?} for {:?}",e.kind,e.path)), +//! Err(errors) => errors.iter().for_each(|e|println!("Error {:?}",e)), +//! } +//! }).unwrap(); +//! +//! // Add a path to be watched. All files and directories at that path and +//! // below will be monitored for changes. +//! debouncer.watcher().watch(Path::new("."), RecursiveMode::Recursive).unwrap(); +//! # } +//! ``` +//! +//! # Features +//! +//! The following feature can be turned on or off. +//! +//! - `crossbeam-channel` enabled by default, adds DebounceEventHandler support for crossbeam channels. +//! - `serde` enabled serde support for events. #[cfg(feature = "serde")] use serde::{Deserialize, Serialize}; use std::{ @@ -17,43 +56,50 @@ use notify::{Error, ErrorKind, Event, RecommendedWatcher, Watcher}; /// /// # Example implementation /// -/// ```no_run -/// use notify::{Event, Result, EventHandler}; +/// ```rust,no_run +/// # use notify::{Event, Result, EventHandler}; +/// # use notify_debouncer_mini::{DebounceEventHandler,DebounceEventResult}; /// /// /// Prints received events /// struct EventPrinter; /// -/// impl EventHandler for EventPrinter { -/// fn handle_event(&mut self, event: Result) { -/// if let Ok(event) = event { -/// println!("Event: {:?}", event); +/// impl DebounceEventHandler for EventPrinter { +/// fn handle_event(&mut self, event: DebounceEventResult) { +/// match event { +/// Ok(events) => { +/// for event in events { +/// println!("Event {:?} for path {:?}",event.kind,event.path); +/// } +/// }, +/// // errors are batched, so you get either events or errors, probably both per debounce tick (two calls) +/// Err(errors) => errors.iter().for_each(|e|println!("Got error {:?}",e)), /// } /// } /// } /// ``` pub trait DebounceEventHandler: Send + 'static { /// Handles an event. - fn handle_event(&mut self, event: DebouncedEvents); + fn handle_event(&mut self, event: DebounceEventResult); } impl DebounceEventHandler for F where - F: FnMut(DebouncedEvents) + Send + 'static, + F: FnMut(DebounceEventResult) + Send + 'static, { - fn handle_event(&mut self, event: DebouncedEvents) { + fn handle_event(&mut self, event: DebounceEventResult) { (self)(event); } } #[cfg(feature = "crossbeam")] -impl DebounceEventHandler for crossbeam_channel::Sender { - fn handle_event(&mut self, event: DebouncedEvents) { +impl DebounceEventHandler for crossbeam_channel::Sender { + fn handle_event(&mut self, event: DebounceEventResult) { let _ = self.send(event); } } -impl DebounceEventHandler for std::sync::mpsc::Sender { - fn handle_event(&mut self, event: DebouncedEvents) { +impl DebounceEventHandler for std::sync::mpsc::Sender { + fn handle_event(&mut self, event: DebounceEventResult) { let _ = self.send(event); } } @@ -76,14 +122,16 @@ impl EventData { } } -type DebouncedEvents = Result, Vec>; +/// A result of debounced events. +/// Comes with either a vec of events or vec of errors. +pub type DebounceEventResult = Result, Vec>; /// A debounced event kind. #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] #[non_exhaustive] pub enum DebouncedEventKind { - /// When precise events are disabled for files + /// No precise events Any, /// Event but debounce timed out (for example continuous writes) AnyContinuous, @@ -204,7 +252,7 @@ impl Drop for Debouncer { /// Creates a new debounced watcher with custom configuration. /// -/// Timeout is the amount of time after which a debounced event is emitted or a Continuous event is send, if there still are events incoming for the specific path. +/// Timeout is the amount of time after which a debounced event is emitted or a continuous event is send, if there still are events incoming for the specific path. /// /// If tick_rate is None, notify will select a tick rate that is less than the provided timeout. pub fn new_debouncer_opt( @@ -285,7 +333,7 @@ pub fn new_debouncer_opt( /// Short function to create a new debounced watcher with the recommended debouncer. /// -/// Timeout is the amount of time after which a debounced event is emitted or a Continuous event is send, if there still are events incoming for the specific path. +/// Timeout is the amount of time after which a debounced event is emitted or a continuous event is send, if there still are events incoming for the specific path. /// /// If tick_rate is None, notify will select a tick rate that is less than the provided timeout. pub fn new_debouncer(