Proof-read some docs and prepare 1.7.0 release

fsnotify · Oct 22, 2023 · c3fa8e6 · c3fa8e6
1 parent 5310461
commit c3fa8e6
Show file tree

Hide file tree

Showing 8 changed files with 96 additions and 78 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 Unreleased
 ----------
+Nothing yet.
+
+1.7.0 - 2023-10-22
+------------------
 This version of fsnotify needs Go 1.17.
 
 ### Additions
@@ -45,20 +49,21 @@ This version of fsnotify needs Go 1.17.
 - kqueue: make sure events for all files are delivered properly when removing a
   watched directory ([#526])
 
-  Previously they would get sent with "" or "." as the path name.
+  Previously they would get sent with `""` (empty string) or `"."` as the path
+  name.
 
 - kqueue: don't emit spurious Create events for symbolic links ([#524])
 
   The link would get resolved but kqueue would "forget" it already saw the link
   itself, resulting on a Create for every Write event for the directory.
 
-- all: return ErrClosed on Add() when the watcher is closed ([#516])
+- all: return `ErrClosed` on `Add()` when the watcher is closed ([#516])
 
 - other: add `Watcher.Errors` and `Watcher.Events` to the no-op `Watcher` in
   `backend_other.go`, making it easier to use on unsupported platforms such as
   WASM, AIX, etc. ([#528])
 
-- other: use the backend_other.go no-op if the `appengine` build tag is set;
+- other: use the `backend_other.go` no-op if the `appengine` build tag is set;
   Google AppEngine forbids usage of the unsafe package so the inotify backend
   won't compile there.
 
@@ -67,6 +72,7 @@ This version of fsnotify needs Go 1.17.
 [#518]: https://github.com/fsnotify/fsnotify/pull/518
 [#520]: https://github.com/fsnotify/fsnotify/pull/520
 [#521]: https://github.com/fsnotify/fsnotify/pull/521
+[#524]: https://github.com/fsnotify/fsnotify/pull/524
 [#525]: https://github.com/fsnotify/fsnotify/pull/525
 [#526]: https://github.com/fsnotify/fsnotify/pull/526
 [#528]: https://github.com/fsnotify/fsnotify/pull/528
@@ -75,7 +81,7 @@ This version of fsnotify needs Go 1.17.
 [#572]: https://github.com/fsnotify/fsnotify/pull/572
 
 1.6.0 - 2022-10-13
--------------------
+------------------
 This version of fsnotify needs Go 1.16 (this was already the case since 1.5.1,
 but not documented). It also increases the minimum Linux version to 2.6.32.
 

diff --git a/README.md b/README.md
@@ -1,7 +1,7 @@
 fsnotify is a Go library to provide cross-platform filesystem notifications on
 Windows, Linux, macOS, BSD, and illumos.
 
-Go 1.16 or newer is required; the full documentation is at
+Go 1.17 or newer is required; the full documentation is at
 https://pkg.go.dev/github.com/fsnotify/fsnotify
 
 ---
@@ -13,7 +13,7 @@ Platform support:
 | inotify               | Linux      | Supported                                                                 |
 | kqueue                | BSD, macOS | Supported                                                                 |
 | ReadDirectoryChangesW | Windows    | Supported                                                                 |
-| FEN                   | illumos    | Supported in main branch                                                  |
+| FEN                   | illumos    | Supported                                                                 |
 | fanotify              | Linux 5.9+ | [Not yet](https://github.com/fsnotify/fsnotify/issues/114)                |
 | AHAFS                 | AIX        | [aix branch]; experimental due to lack of maintainer and test environment |
 | FSEvents              | macOS      | [Needs support in x/sys/unix][fsevents]                                   |

diff --git a/backend_fen.go b/backend_fen.go
@@ -117,8 +117,8 @@ type Watcher struct {
 	//   fsnotify.Chmod     Attributes were changed. On Linux this is also sent
 	//                      when a file is removed (or more accurately, when a
 	//                      link to an inode is removed). On kqueue it's sent
-	//                      and on kqueue when a file is truncated. On Windows
-	//                      it's never sent.
+	//                      when a file is truncated. On Windows it's never
+	//                      sent.
 	Events chan Event
 
 	// Errors sends any errors.
@@ -142,9 +142,10 @@ func NewWatcher() (*Watcher, error) {
 	return NewBufferedWatcher(0)
 }
 
-// NewBufferedWatcher creates a new Watcher with a buffered [Events] channel.
+// NewBufferedWatcher creates a new Watcher with a buffered [Watcher.Events]
+// channel.
 //
-// The main use-case for this is situations with a very large number of events
+// The main use case for this is situations with a very large number of events
 // where the kernel buffer size can't be increased (e.g. due to lack of
 // permissions). An unbuffered Watcher will perform better for almost all use
 // cases, and whenever possible you will be better off increasing the kernel
@@ -199,7 +200,7 @@ func (w *Watcher) isClosed() bool {
 	}
 }
 
-// Close removes all watches and closes the events channel.
+// Close removes all watches and closes the Events channel.
 func (w *Watcher) Close() error {
 	// Take the lock used by associateFile to prevent lingering events from
 	// being processed after the close
@@ -215,7 +216,7 @@ func (w *Watcher) Close() error {
 // Add starts monitoring the path for changes.
 //
 // A path can only be watched once; watching it more than once is a no-op and will
-// not return an error. Paths that do not yet exist on the filesystem cannot
+// not return an error. Paths that do not yet exist on the filesystem cannot be
 // watched.
 //
 // A watch will be automatically removed if the watched path is deleted or
@@ -227,7 +228,7 @@ func (w *Watcher) Close() error {
 //
 // Returns [ErrClosed] if [Watcher.Close] was called.
 //
-// See [AddWith] for a version that allows adding options.
+// See [Watcher.AddWith] for a version that allows adding options.
 //
 // # Watching directories
 //
@@ -246,12 +247,12 @@ func (w *Watcher) Close() error {
 // The upshot of this is that a power failure or crash won't leave a
 // half-written file.
 //
-// Watch the parent directory and use [Event.Name] to filter out files you're
-// not interested in. There is an example of this in [cmd/fsnotify/file.go].
+// Watch the parent directory and use Event.Name to filter out files you're not
+// interested in. There is an example of this in cmd/fsnotify/file.go.
 func (w *Watcher) Add(name string) error { return w.AddWith(name) }
 
-// AddWith is like [Add], but allows adding options. When using Add() the
-// defaults described below are used.
+// AddWith is like [Watcher.Add], but allows adding options. When using Add()
+// the defaults described below are used.
 //
 // Possible options are:
 //
@@ -615,7 +616,8 @@ func (w *Watcher) dissociateFile(path string, stat os.FileInfo, unused bool) err
 	return w.port.DissociatePath(path)
 }
 
-// WatchList returns all paths added with [Add] (and are not yet removed).
+// WatchList returns all paths explicitly added with [Watcher.Add] (and are not
+// yet removed).
 //
 // Returns nil if [Watcher.Close] was called.
 func (w *Watcher) WatchList() []string {

diff --git a/backend_inotify.go b/backend_inotify.go
@@ -120,8 +120,8 @@ type Watcher struct {
 	//   fsnotify.Chmod     Attributes were changed. On Linux this is also sent
 	//                      when a file is removed (or more accurately, when a
 	//                      link to an inode is removed). On kqueue it's sent
-	//                      and on kqueue when a file is truncated. On Windows
-	//                      it's never sent.
+	//                      when a file is truncated. On Windows it's never
+	//                      sent.
 	Events chan Event
 
 	// Errors sends any errors.
@@ -241,9 +241,10 @@ func NewWatcher() (*Watcher, error) {
 	return NewBufferedWatcher(0)
 }
 
-// NewBufferedWatcher creates a new Watcher with a buffered [Events] channel.
+// NewBufferedWatcher creates a new Watcher with a buffered [Watcher.Events]
+// channel.
 //
-// The main use-case for this is situations with a very large number of events
+// The main use case for this is situations with a very large number of events
 // where the kernel buffer size can't be increased (e.g. due to lack of
 // permissions). An unbuffered Watcher will perform better for almost all use
 // cases, and whenever possible you will be better off increasing the kernel
@@ -299,7 +300,7 @@ func (w *Watcher) isClosed() bool {
 	}
 }
 
-// Close removes all watches and closes the events channel.
+// Close removes all watches and closes the Events channel.
 func (w *Watcher) Close() error {
 	w.closeMu.Lock()
 	if w.isClosed() {
@@ -325,7 +326,7 @@ func (w *Watcher) Close() error {
 // Add starts monitoring the path for changes.
 //
 // A path can only be watched once; watching it more than once is a no-op and will
-// not return an error. Paths that do not yet exist on the filesystem cannot
+// not return an error. Paths that do not yet exist on the filesystem cannot be
 // watched.
 //
 // A watch will be automatically removed if the watched path is deleted or
@@ -337,7 +338,7 @@ func (w *Watcher) Close() error {
 //
 // Returns [ErrClosed] if [Watcher.Close] was called.
 //
-// See [AddWith] for a version that allows adding options.
+// See [Watcher.AddWith] for a version that allows adding options.
 //
 // # Watching directories
 //
@@ -356,12 +357,12 @@ func (w *Watcher) Close() error {
 // The upshot of this is that a power failure or crash won't leave a
 // half-written file.
 //
-// Watch the parent directory and use [Event.Name] to filter out files you're
-// not interested in. There is an example of this in [cmd/fsnotify/file.go].
+// Watch the parent directory and use Event.Name to filter out files you're not
+// interested in. There is an example of this in cmd/fsnotify/file.go.
 func (w *Watcher) Add(name string) error { return w.AddWith(name) }
 
-// AddWith is like [Add], but allows adding options. When using Add() the
-// defaults described below are used.
+// AddWith is like [Watcher.Add], but allows adding options. When using Add()
+// the defaults described below are used.
 //
 // Possible options are:
 //
@@ -441,7 +442,8 @@ func (w *Watcher) remove(name string) error {
 	return nil
 }
 
-// WatchList returns all paths added with [Add] (and are not yet removed).
+// WatchList returns all paths explicitly added with [Watcher.Add] (and are not
+// yet removed).
 //
 // Returns nil if [Watcher.Close] was called.
 func (w *Watcher) WatchList() []string {

diff --git a/backend_kqueue.go b/backend_kqueue.go
@@ -117,8 +117,8 @@ type Watcher struct {
 	//   fsnotify.Chmod     Attributes were changed. On Linux this is also sent
 	//                      when a file is removed (or more accurately, when a
 	//                      link to an inode is removed). On kqueue it's sent
-	//                      and on kqueue when a file is truncated. On Windows
-	//                      it's never sent.
+	//                      when a file is truncated. On Windows it's never
+	//                      sent.
 	Events chan Event
 
 	// Errors sends any errors.
@@ -153,9 +153,10 @@ func NewWatcher() (*Watcher, error) {
 	return NewBufferedWatcher(0)
 }
 
-// NewBufferedWatcher creates a new Watcher with a buffered [Events] channel.
+// NewBufferedWatcher creates a new Watcher with a buffered [Watcher.Events]
+// channel.
 //
-// The main use-case for this is situations with a very large number of events
+// The main use case for this is situations with a very large number of events
 // where the kernel buffer size can't be increased (e.g. due to lack of
 // permissions). An unbuffered Watcher will perform better for almost all use
 // cases, and whenever possible you will be better off increasing the kernel
@@ -239,7 +240,7 @@ func (w *Watcher) sendError(err error) bool {
 	}
 }
 
-// Close removes all watches and closes the events channel.
+// Close removes all watches and closes the Events channel.
 func (w *Watcher) Close() error {
 	w.mu.Lock()
 	if w.isClosed {
@@ -268,7 +269,7 @@ func (w *Watcher) Close() error {
 // Add starts monitoring the path for changes.
 //
 // A path can only be watched once; watching it more than once is a no-op and will
-// not return an error. Paths that do not yet exist on the filesystem cannot
+// not return an error. Paths that do not yet exist on the filesystem cannot be
 // watched.
 //
 // A watch will be automatically removed if the watched path is deleted or
@@ -280,7 +281,7 @@ func (w *Watcher) Close() error {
 //
 // Returns [ErrClosed] if [Watcher.Close] was called.
 //
-// See [AddWith] for a version that allows adding options.
+// See [Watcher.AddWith] for a version that allows adding options.
 //
 // # Watching directories
 //
@@ -299,12 +300,12 @@ func (w *Watcher) Close() error {
 // The upshot of this is that a power failure or crash won't leave a
 // half-written file.
 //
-// Watch the parent directory and use [Event.Name] to filter out files you're
-// not interested in. There is an example of this in [cmd/fsnotify/file.go].
+// Watch the parent directory and use Event.Name to filter out files you're not
+// interested in. There is an example of this in cmd/fsnotify/file.go.
 func (w *Watcher) Add(name string) error { return w.AddWith(name) }
 
-// AddWith is like [Add], but allows adding options. When using Add() the
-// defaults described below are used.
+// AddWith is like [Watcher.Add], but allows adding options. When using Add()
+// the defaults described below are used.
 //
 // Possible options are:
 //
@@ -390,7 +391,8 @@ func (w *Watcher) remove(name string, unwatchFiles bool) error {
 	return nil
 }
 
-// WatchList returns all paths added with [Add] (and are not yet removed).
+// WatchList returns all paths explicitly added with [Watcher.Add] (and are not
+// yet removed).
 //
 // Returns nil if [Watcher.Close] was called.
 func (w *Watcher) WatchList() []string {

diff --git a/backend_other.go b/backend_other.go
@@ -109,8 +109,8 @@ type Watcher struct {
 	//   fsnotify.Chmod     Attributes were changed. On Linux this is also sent
 	//                      when a file is removed (or more accurately, when a
 	//                      link to an inode is removed). On kqueue it's sent
-	//                      and on kqueue when a file is truncated. On Windows
-	//                      it's never sent.
+	//                      when a file is truncated. On Windows it's never
+	//                      sent.
 	Events chan Event
 
 	// Errors sends any errors.
@@ -128,27 +128,29 @@ func NewWatcher() (*Watcher, error) {
 	return nil, errors.New("fsnotify not supported on the current platform")
 }
 
-// NewBufferedWatcher creates a new Watcher with a buffered [Events] channel.
+// NewBufferedWatcher creates a new Watcher with a buffered [Watcher.Events]
+// channel.
 //
-// The main use-case for this is situations with a very large number of events
+// The main use case for this is situations with a very large number of events
 // where the kernel buffer size can't be increased (e.g. due to lack of
 // permissions). An unbuffered Watcher will perform better for almost all use
 // cases, and whenever possible you will be better off increasing the kernel
 // buffers instead of adding a large userspace buffer.
 func NewBufferedWatcher(sz uint) (*Watcher, error) { return NewWatcher() }
 
-// Close removes all watches and closes the events channel.
+// Close removes all watches and closes the Events channel.
 func (w *Watcher) Close() error { return nil }
 
-// WatchList returns all paths added with [Add] (and are not yet removed).
+// WatchList returns all paths explicitly added with [Watcher.Add] (and are not
+// yet removed).
 //
 // Returns nil if [Watcher.Close] was called.
 func (w *Watcher) WatchList() []string { return nil }
 
 // Add starts monitoring the path for changes.
 //
 // A path can only be watched once; watching it more than once is a no-op and will
-// not return an error. Paths that do not yet exist on the filesystem cannot
+// not return an error. Paths that do not yet exist on the filesystem cannot be
 // watched.
 //
 // A watch will be automatically removed if the watched path is deleted or
@@ -160,7 +162,7 @@ func (w *Watcher) WatchList() []string { return nil }
 //
 // Returns [ErrClosed] if [Watcher.Close] was called.
 //
-// See [AddWith] for a version that allows adding options.
+// See [Watcher.AddWith] for a version that allows adding options.
 //
 // # Watching directories
 //
@@ -179,12 +181,12 @@ func (w *Watcher) WatchList() []string { return nil }
 // The upshot of this is that a power failure or crash won't leave a
 // half-written file.
 //
-// Watch the parent directory and use [Event.Name] to filter out files you're
-// not interested in. There is an example of this in [cmd/fsnotify/file.go].
+// Watch the parent directory and use Event.Name to filter out files you're not
+// interested in. There is an example of this in cmd/fsnotify/file.go.
 func (w *Watcher) Add(name string) error { return nil }
 
-// AddWith is like [Add], but allows adding options. When using Add() the
-// defaults described below are used.
+// AddWith is like [Watcher.Add], but allows adding options. When using Add()
+// the defaults described below are used.
 //
 // Possible options are:
 //