Document events a bit better

Fixes #529

README.md

@@ -14,14 +14,17 @@ Platform support:
 | kqueue                | BSD, macOS     | Supported                                                    |
 | ReadDirectoryChangesW | Windows        | Supported                                                    |
 | FEN                   | illumos        | Supported in main branch                                     |
-| FSEvents              | macOS          | [Not yet](https://github.com/fsnotify/fsnotify/issues/11)    |
+| FSEvents              | macOS          | [Needs support in x/sys/unix][fsevents]                      |
 | fanotify              | Linux 5.9+     | [Not yet](https://github.com/fsnotify/fsnotify/issues/114)   |
-| USN Journals          | Windows        | [Maybe](https://github.com/fsnotify/fsnotify/issues/53)      |
+| USN Journals          | Windows        | [Needs support in x/sys/windows][usn]                        |
 | Polling               | *All*          | [Not yet](https://github.com/fsnotify/fsnotify/issues/9)     |
 
 Linux, macOS, and illumos should include Android, iOS, and Solaris, but these
 are currently untested.
 
+[fsevents]: https://github.com/fsnotify/fsnotify/issues/11#issuecomment-1279133120
+[usn]:      https://github.com/fsnotify/fsnotify/issues/53#issuecomment-1279829847
+
 Usage
 -----
 A basic example:
@@ -80,6 +83,9 @@ run with:
 
     % go run ./cmd/fsnotify
 
+Further detailed documentation can be found in godoc:
+https://pkg.go.dev/github.com/fsnotify/fsnotify
+
 FAQ
 ---
 ### Will a file still be watched when it's moved to another directory?
@@ -104,6 +110,19 @@ This could be fixed with a polling watcher ([#9]), but it's not yet implemented.
 
 [#9]: https://github.com/fsnotify/fsnotify/issues/9
 
+### Why do I get many Chmod events?
+Some programs may generate a lot of attribute changes; for example Spotlight on
+macOS, anti-virus programs, backup applications, and some others are known to do
+this. As a rule, it's typically best to ignore Chmod events. They're often not
+useful, and tend to cause problems.
+
+Spotlight indexing on macOS can result in multiple events (see [#15]). A
+temporary workaround is to add your folder(s) to the *Spotlight Privacy
+settings* until we have a native FSEvents implementation (see [#11]).
+
+[#11]: https://github.com/fsnotify/fsnotify/issues/11
+[#15]: https://github.com/fsnotify/fsnotify/issues/15
+
 Platform-specific notes
 -----------------------
 ### Linux
@@ -148,11 +167,3 @@ these platforms.
 
 The sysctl variables `kern.maxfiles` and `kern.maxfilesperproc` can be used to
 control the maximum number of open files.
-
-### macOS
-Spotlight indexing on macOS can result in multiple events (see [#15]). A temporary
-workaround is to add your folder(s) to the *Spotlight Privacy settings* until we
-have a native FSEvents implementation (see [#11]).
-
-[#11]: https://github.com/fsnotify/fsnotify/issues/11
-[#15]: https://github.com/fsnotify/fsnotify/issues/15

backend_fen.go

@@ -63,15 +63,6 @@ import (
 // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
 // control the maximum number of open files, as well as /etc/login.conf on BSD
 // systems.
-//
-// # macOS notes
-//
-// Spotlight indexing on macOS can result in multiple events (see [#15]). A
-// temporary workaround is to add your folder(s) to the "Spotlight Privacy
-// Settings" until we have a native FSEvents implementation (see [#11]).
-//
-// [#11]: https://github.com/fsnotify/fsnotify/issues/11
-// [#15]: https://github.com/fsnotify/fsnotify/issues/15
 type Watcher struct {
 	// Events sends the filesystem change events.
 	//
@@ -111,7 +102,7 @@ type Watcher struct {
 
 	// Errors sends any errors.
 	//
-	// [ErrEventOverflow] is used to indicate ther are too many events:
+	// [ErrEventOverflow] is used to indicate there are too many events:
 	//
 	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
 	//  - windows: The buffer size is too small.

backend_inotify.go

@@ -66,15 +66,6 @@ import (
 // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
 // control the maximum number of open files, as well as /etc/login.conf on BSD
 // systems.
-//
-// # macOS notes
-//
-// Spotlight indexing on macOS can result in multiple events (see [#15]). A
-// temporary workaround is to add your folder(s) to the "Spotlight Privacy
-// Settings" until we have a native FSEvents implementation (see [#11]).
-//
-// [#11]: https://github.com/fsnotify/fsnotify/issues/11
-// [#15]: https://github.com/fsnotify/fsnotify/issues/15
 type Watcher struct {
 	// Events sends the filesystem change events.
 	//
@@ -114,7 +105,7 @@ type Watcher struct {
 
 	// Errors sends any errors.
 	//
-	// [ErrEventOverflow] is used to indicate ther are too many events:
+	// [ErrEventOverflow] is used to indicate there are too many events:
 	//
 	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
 	//  - windows: The buffer size is too small.

backend_kqueue.go

@@ -64,15 +64,6 @@ import (
 // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
 // control the maximum number of open files, as well as /etc/login.conf on BSD
 // systems.
-//
-// # macOS notes
-//
-// Spotlight indexing on macOS can result in multiple events (see [#15]). A
-// temporary workaround is to add your folder(s) to the "Spotlight Privacy
-// Settings" until we have a native FSEvents implementation (see [#11]).
-//
-// [#11]: https://github.com/fsnotify/fsnotify/issues/11
-// [#15]: https://github.com/fsnotify/fsnotify/issues/15
 type Watcher struct {
 	// Events sends the filesystem change events.
 	//
@@ -112,7 +103,7 @@ type Watcher struct {
 
 	// Errors sends any errors.
 	//
-	// [ErrEventOverflow] is used to indicate ther are too many events:
+	// [ErrEventOverflow] is used to indicate there are too many events:
 	//
 	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
 	//  - windows: The buffer size is too small.

backend_other.go

@@ -58,15 +58,6 @@ import (
 // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
 // control the maximum number of open files, as well as /etc/login.conf on BSD
 // systems.
-//
-// # macOS notes
-//
-// Spotlight indexing on macOS can result in multiple events (see [#15]). A
-// temporary workaround is to add your folder(s) to the "Spotlight Privacy
-// Settings" until we have a native FSEvents implementation (see [#11]).
-//
-// [#11]: https://github.com/fsnotify/fsnotify/issues/11
-// [#15]: https://github.com/fsnotify/fsnotify/issues/15
 type Watcher struct {
 	// Events sends the filesystem change events.
 	//
@@ -106,7 +97,7 @@ type Watcher struct {
 
 	// Errors sends any errors.
 	//
-	// [ErrEventOverflow] is used to indicate ther are too many events:
+	// [ErrEventOverflow] is used to indicate there are too many events:
 	//
 	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
 	//  - windows: The buffer size is too small.

backend_windows.go

@@ -67,15 +67,6 @@ import (
 // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
 // control the maximum number of open files, as well as /etc/login.conf on BSD
 // systems.
-//
-// # macOS notes
-//
-// Spotlight indexing on macOS can result in multiple events (see [#15]). A
-// temporary workaround is to add your folder(s) to the "Spotlight Privacy
-// Settings" until we have a native FSEvents implementation (see [#11]).
-//
-// [#11]: https://github.com/fsnotify/fsnotify/issues/11
-// [#15]: https://github.com/fsnotify/fsnotify/issues/15
 type Watcher struct {
 	// Events sends the filesystem change events.
 	//
@@ -115,7 +106,7 @@ type Watcher struct {
 
 	// Errors sends any errors.
 	//
-	// [ErrEventOverflow] is used to indicate ther are too many events:
+	// [ErrEventOverflow] is used to indicate there are too many events:
 	//
 	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
 	//  - windows: The buffer size is too small.

fsnotify.go

@@ -37,10 +37,27 @@ type Op uint32
 // The operations fsnotify can trigger; see the documentation on [Watcher] for a
 // full description, and check them with [Event.Has].
 const (
+	// A new pathname was created.
 	Create Op = 1 << iota
+
+	// The pathname was written to; this does *not* mean the write has finished,
+	// and a write can be followed by more writes.
 	Write
+
+	// The path was removed; any watches on it will be removed. Some "remove"
+	// operations may trigger a Rename if the file is actually moved (for
+	// example "remove to trash" is often a rename).
 	Remove
+
+	// The path was renamed to something else; any watched on it will be
+	// removed.
 	Rename
+
+	// File attributes were changed.
+	//
+	// It's generally not recommended to take action on this event, as it may
+	// get triggered very frequently by some software. For example, Spotlight
+	// indexing on macOS, anti-virus software, backup software, etc.
 	Chmod
 )
 

mkdoc.zsh

@@ -56,15 +56,6 @@ watcher=$(<<EOF
 // The sysctl variables kern.maxfiles and kern.maxfilesperproc can be used to
 // control the maximum number of open files, as well as /etc/login.conf on BSD
 // systems.
-//
-// # macOS notes
-//
-// Spotlight indexing on macOS can result in multiple events (see [#15]). A
-// temporary workaround is to add your folder(s) to the "Spotlight Privacy
-// Settings" until we have a native FSEvents implementation (see [#11]).
-//
-// [#11]: https://github.com/fsnotify/fsnotify/issues/11
-// [#15]: https://github.com/fsnotify/fsnotify/issues/15
 EOF
 )
 
@@ -172,7 +163,7 @@ EOF
 errors=$(<<EOF
 	// Errors sends any errors.
 	//
-	// [ErrEventOverflow] is used to indicate ther are too many events:
+	// [ErrEventOverflow] is used to indicate there are too many events:
 	//
 	//  - inotify: there are too many queued events (fs.inotify.max_queued_events sysctl)
 	//  - windows: The buffer size is too small.