From a718eab9d4f32befe9c14f476b990338be9a5733 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fe=CC=81lix=20Saparelli?= <felix@passcod.name>
Date: Sat, 20 Apr 2019 22:26:47 +1200
Subject: [PATCH] [events] Add Flag::Rescan and improve Any/Other documentation

---
 src/debounce/mod.rs |  6 +++---
 src/event.rs        | 24 ++++++++++++++++++++++--
 2 files changed, 25 insertions(+), 5 deletions(-)

diff --git a/src/debounce/mod.rs b/src/debounce/mod.rs
index c655c304..b864c50f 100644
--- a/src/debounce/mod.rs
+++ b/src/debounce/mod.rs
@@ -78,7 +78,7 @@ impl EventTx {
             } => {
                 match (event.path, event.op, event.cookie) {
                     (None, Ok(op::Op::RESCAN), None) => {
-                        tx.send(Event::new(EventKind::Other).set_info("rescan"))
+                        tx.send(Event::new(EventKind::Other).set_flag(event::Flag::Rescan))
                             .ok();
                     }
                     (Some(path), Ok(op), cookie) => {
@@ -103,7 +103,7 @@ impl EventTx {
             EventTx::DebouncedTx { ref tx } => {
                 match (event.path, event.op, event.cookie) {
                     (None, Ok(op::Op::RESCAN), None) => {
-                        tx.send(Event::new(EventKind::Other).set_info("rescan"))
+                        tx.send(Event::new(EventKind::Other).set_flag(event::Flag::Rescan))
                             .ok();
                     }
                     (Some(_path), Ok(_op), _cookie) => {
@@ -253,7 +253,7 @@ impl Debounce {
     pub fn event(&mut self, path: PathBuf, mut op: op::Op, cookie: Option<u32>) {
         if op.contains(op::Op::RESCAN) {
             self.tx
-                .send(Event::new(EventKind::Other).set_info("rescan"))
+                .send(Event::new(EventKind::Other).set_flag(event::Flag::Rescan))
                 .ok();
         }
 
diff --git a/src/event.rs b/src/event.rs
index debc6323..7d433de1 100644
--- a/src/event.rs
+++ b/src/event.rs
@@ -205,6 +205,8 @@ pub enum EventKind {
     /// This variant should be used as the "else" case when mapping native kernel bitmasks or
     /// bitmaps, such that if the mask is ever extended with new event types the backend will not
     /// gain bugs due to not matching new unknown event types.
+    ///
+    /// This variant is also the default variant used when Notify is in "imprecise" mode.
     Any,
 
     /// An event describing non-mutating access operations on files.
@@ -213,7 +215,7 @@ pub enum EventKind {
     /// other such event that is about accessing files, folders, or other structures rather than
     /// mutating them.
     ///
-    /// Only backends with the `EmitOnAccess` capability will generate these.
+    /// Only some platforms are capable of generating these.
     Access(AccessKind),
 
     /// An event describing creation operations on files.
@@ -240,7 +242,8 @@ pub enum EventKind {
 
     /// An event not fitting in any of the above four categories.
     ///
-    /// This may be used for meta-events about the watch itself, but generally should not be used.
+    /// This may be used for meta-events about the watch itself. In "imprecise" mode, it is, along
+    /// with `Any`, the only other event generated.
     Other,
 }
 
@@ -276,6 +279,14 @@ impl EventKind {
             _ => false,
         }
     }
+
+    /// Indicates whether an event is an Other variant.
+    pub fn is_other(&self) -> bool {
+        match *self {
+            EventKind::Other => true,
+            _ => false
+        }
+    }
 }
 
 impl Default for EventKind {
@@ -390,6 +401,15 @@ pub enum Flag {
     ///
     /// Ongoing event notices are a runtime option and are disabled by default.
     Ongoing,
+
+    /// Rescan notices are emitted by some platforms (and may also be emitted by Notify itself).
+    /// They indicate either a lapse in the events or a change in the filesystem such that events
+    /// received so far can no longer be relied on to represent the state of the filesystem now.
+    ///
+    /// An application that simply reacts to file changes may not care about this. An application
+    /// that keeps an in-memory representation of the filesystem will need to care, and will need
+    /// to refresh that representation directly from the filesystem.
+    Rescan,
 }
 
 /// Additional information on the event.