New unwind-protect flavors to better type-check C callbacks.

[bpt/emacs.git] / src / w32notify.c

diff --git a/src/w32notify.c b/src/w32notify.c
index 3095103..95ab298 100644 (file)
--- a/src/w32notify.c
+++ b/src/w32notify.c
@@ -1,5 +1,5 @@
 /* Filesystem notifications support for GNU Emacs on the Microsoft Windows API.
-   Copyright (C) 2012  Free Software Foundation, Inc.
+   Copyright (C) 2012-2013 Free Software Foundation, Inc.
 
 This file is part of GNU Emacs.
 
@@ -39,7 +39,7 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
    return, and watch_worker then issues another call to
    ReadDirectoryChangesW.  (Except when it does not, see below.)
 
-   In a GUI session, The WM_EMACS_FILENOTIFY message, posted to the
+   In a GUI session, the WM_EMACS_FILENOTIFY message posted to the
    message queue gets dispatched to the main Emacs window procedure,
    which queues it for processing by w32_read_socket.  When
    w32_read_socket sees this message, it accesses the buffer with file
@@ -59,7 +59,7 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
 
    When the FILE_NOTIFY_EVENT event is processed by keyboard.c's
    kbd_buffer_get_event, it is converted to a Lispy event that can be
-   bound to a command.  The default binding is w32notify-handle-event,
+   bound to a command.  The default binding is file-notify-handle-event,
    defined on subr.el.
 
    After w32_read_socket or w32_console_read_socket are done
@@ -217,7 +217,7 @@ watch_completion (DWORD status, DWORD bytes_ret, OVERLAPPED *io_info)
       /* We've been called because the main thread told us to issue
         CancelIo on the directory we watch, and watch_end did so.
         The directory handle is already closed.  We should clean up
-        and exit, signalling to the thread worker routine not to
+        and exit, signaling to the thread worker routine not to
         issue another call to ReadDirectoryChangesW.  Note that we
         don't free the dirwatch object itself nor the memory consumed
         by its buffers; this is done by the main thread in
@@ -442,8 +442,8 @@ DEFUN ("w32notify-add-watch", Fw32notify_add_watch,
 This arranges for filesystem events pertaining to FILE to be reported
 to Emacs.  Use `w32notify-rm-watch' to cancel the watch.
 
-Value is a descriptor for the added watch, or nil if the file
-cannot be watched.
+Value is a descriptor for the added watch.  If the file cannot be
+watched for some reason, this function signals a `file-error' error.
 
 FILTER is a list of conditions for reporting an event.  It can include
 the following symbols:
@@ -476,7 +476,13 @@ following:
   'renamed-from' -- a file was renamed whose old name was FILE
   'renamed-to'   -- a file was renamed and its new name is FILE
 
-FILE is the name of the file whose event is being reported.  */)
+FILE is the name of the file whose event is being reported.
+
+Note that some networked filesystems, such as Samba-mounted Unix
+volumes, might not send notifications about file changes.  In these
+cases, this function will return a valid descriptor, but notifications
+will never come in.  Volumes shared from remote Windows machines do
+generate notifications correctly, though.  */)
   (Lisp_Object file, Lisp_Object filter, Lisp_Object callback)
 {
   Lisp_Object encoded_file, watch_object, watch_descriptor;