Document file notification `stopped' event

* doc/lispref/os.texi (File Notifications): Document `stopped event'.

2 files changed, 45 insertions, 3 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 1925bd544e5..0160de82086 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2632,6 +2632,8 @@ reports attribute changes as well
 @var{file} has been renamed to @var{file1}
 @item attribute-changed
 a @var{file} attribute was changed
+@item stopped
+watching @var{file} has been stopped
 @end table
 
 Note that the @file{w32notify} library does not report
@@ -2639,6 +2641,11 @@ Note that the @file{w32notify} library does not report
 permissions or modification time, has changed, this library reports a
 @code{changed} event.
 
+The @code{stopped} event reports, that watching the file has been
+stopped.  This could be because @code{file-notify-rm-watch} was called
+(see below), or because the file being watched was deleted, or due to
+another error reported from the underlying library.
+
 @var{file} and @var{file1} are the name of the file(s) whose event is
 being reported.  For example:
 
@@ -2708,6 +2715,36 @@ A watch can become invalid if the file or directory it watches is
 deleted, or if the watcher thread exits abnormally for any other
 reason.  Removing the watch by calling @code{file-notify-rm-watch}
 also makes it invalid.
+
+@example
+@group
+(setq desc (file-notify-add-watch
+             "/tmp/foo" '(change) 'my-notify-callback))
+     @result{} 35025468
+@end group
+
+@group
+(write-region "foo" nil "/tmp/foo")
+     @result{} Event (35025468 created "/tmp/foo")
+        Event (35025468 changed "/tmp/foo")
+@end group
+
+@group
+(file-notify-valid-p desc)
+     @result{} t
+@end group
+
+@group
+(delete-file "/tmp/foo")
+     @result{} Event (35025468 deleted "/tmp/foo")
+        Event (35025468 stopped "/tmp/foo")
+@end group
+
+@group
+(file-notify-valid-p desc)
+     @result{} nil
+@end group
+@end example
 @end defun
 
 @node Dynamic Libraries
diff --git a/etc/NEWS b/etc/NEWS
index 381e7c841a9..f5b06f95fb0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -843,10 +843,15 @@ be added to the archive.
 ** Autorevert: dired buffers are also auto-reverted via file
 notifications, if Emacs is compiled with file notification support.
 
+** File Notifications
+
++++
+*** The new event `stopped' signals, that a file notification watch is
+not active any longer.
+
 +++
-** File Notifications: the new function `file-notify-valid-p' checks,
-whether a file notification descriptor still corresponds to an
-activate watch.
+*** The new function `file-notify-valid-p' checks, whether a file
+notification descriptor still corresponds to an activate watch.
 
 ** Dired