documentation and examples

.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: "CI"
+on: ["push", "pull_request"]
+
+jobs:
+  ci:
+    name: "Run CI"
+    strategy:
+      fail-fast: false
+      matrix:
+        os:  ["windows-latest", "ubuntu-latest", "macOS-latest"]
+        go:  ["1.18.x"]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 1
+    - uses: WillAbides/setup-go-faster@v1.7.0
+      with:
+        go-version: ${{ matrix.go }}
+    - run: "go test -v ./..."
+    - run: "go vet ./..."
+    - uses: dominikh/staticcheck-action@v1.2.0
+      with:
+        version: "2022.1"
+        install-go: false
+        cache-key: ${{ matrix.go }}
+        working-directory: ${{ matrix.dir }}

README.md

@@ -1,36 +1,104 @@
 # Watcher
 
+![CI Status](https://github.com/wilhelm-murdoch/go-watcher/actions/workflows/ci.yml/badge.svg)
+[![GoDoc](https://godoc.org/github.com/wilhelm-murdoch/go-watcher?status.svg)](https://pkg.go.dev/github.com/wilhelm-murdoch/go-watcher)
+[![Go report](https://goreportcard.com/badge/github.com/wilhelm-murdoch/go-watcher)](https://goreportcard.com/report/github.com/wilhelm-murdoch/go-watcher)
+[![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)
+
 A no-nonsense wrapper around the [fsnotify](https://pkg.go.dev/github.com/fsnotify/fsnotify) package.
 
 ## Install
 ```
 $ go get github.com/wilhelm-murdoch/go-watcher
 ```
 
-## Usage
+# Reference
+
+* [New](#Function-New)
+* [AddPath](#Function-AddPath)
+* [WalkPath](#Function-WalkPath)
+* [AddGlob](#Function-AddGlob)
+* [On](#Function-On)
+* [All](#Function-All)
+* [Watch](#Function-Watch)
+* [List](#Function-List)
+* [Done](#Function-Done)
+
+
+### Function `New`
+* `func New() (*Watcher, error)` [#](watcher.go#L24)
+* `watcher.go:24:31` [#](watcher.go#L24-L31)
+
+New creates a new instance of a Watcher struct. 
+
+### Function `AddPath`
+* `func (w *Watcher) AddPath(path string) error` [#](watcher.go#L35)
+* `watcher.go:35:37` [#](watcher.go#L35-L37)
+
+AddFile adds a single valid file to the current Watcher instance and returns an error if the file is not valid. 
+
+### Function `WalkPath`
+* `func (w *Watcher) WalkPath(path string) error` [#](watcher.go#L41)
+* `watcher.go:41:55` [#](watcher.go#L41-L55)
+
+AddDir will recursively walk the specified directory tree and add all valid files to the current watcher instance for monitoring. 
+
+### Function `AddGlob`
+* `func (w *Watcher) AddGlob(pattern string) error` [#](watcher.go#L59)
+* `watcher.go:59:70` [#](watcher.go#L59-L70)
+
+AddGlob will monitor the specified "glob" pattern and add all valid files to the current watcher instance for monitoring. 
+
+### Function `On`
+* `func (w *Watcher) On(event fsnotify.Op, f func(fsnotify.Event, os.FileInfo, error) error) error` [#](watcher.go#L75)
+* `watcher.go:75:94` [#](watcher.go#L75-L94)
+
+On fires off an assigned callback for each event type. Only specified events are supported and all will return either nil or an error. Every watcher instance exits when it first encounters an error. 
 
-Watch for new files in `/path/to/files` and stop the watcher on the first `fsnotify.Create` event.
+### Function `All`
+* `func (w *Watcher) All(f func(fsnotify.Event, os.FileInfo, error) error)` [#](watcher.go#L97)
+* `watcher.go:97:100` [#](watcher.go#L97-L100)
+
+All will fire off the specified callback on any supported `fsnotify` event. 
+
+### Function `Watch`
+* `func (w *Watcher) Watch() error` [#](watcher.go#L105)
+* `watcher.go:105:161` [#](watcher.go#L105-L161)
+
+Watch creates a new `errgroup` instance and monitors for changes to any of the specified files. All supported event types will fire off specified callbacks if available. This method exits on the first encountered error. 
 
 ```go
-package main 
+package main
 
 import (
   "fmt"
+  "strings"
 
-  "github.com/wilhelm-murdoch/go-watcher"
+  "github.com/wilhelm-murdoch/go-play"
 )
 
 func main() {
-  w, err := watcher.New()
+
+}
+```
 
-  w.AddDir("/path/to/files")
+### Function `List`
+* `func (w *Watcher) List() []string` [#](watcher.go#L166)
+* `watcher.go:166:168` [#](watcher.go#L166-L168)
 
-  w.On(fsnotify.Create, func(file os.FileInfo, err error) error {
-    fmt.Println("new file:", file.Name())
-    w.Done()
-    return nil
-  })
+List is a wrapper around `fsnotify.Watchlist()`. It returns a list of strings representing all files and directories currently monitored instance of `fsnotify`. 
 
-  w.Watch()
-}
-```
+### Function `Done`
+* `func (w *Watcher) Done()` [#](watcher.go#L172)
+* `watcher.go:172:174` [#](watcher.go#L172-L174)
+
+Done signals a blocking channel that processing is complete and that we can safely exit the current watcher instance. 
+
+
+
+Documentation generated by [Gadget](https://github.com/wilhelm-murdoch/go-gadget).
+
+# License
+Copyright © 2022 [Wilhelm Murdoch](https://wilhelm.codes).
+
+This project is [MIT](./LICENSE) licensed.

README.tpl

@@ -0,0 +1,50 @@
+# Watcher
+
+![CI Status](https://github.com/wilhelm-murdoch/go-watcher/actions/workflows/ci.yml/badge.svg)
+[![GoDoc](https://godoc.org/github.com/wilhelm-murdoch/go-watcher?status.svg)](https://pkg.go.dev/github.com/wilhelm-murdoch/go-watcher)
+[![Go report](https://goreportcard.com/badge/github.com/wilhelm-murdoch/go-watcher)](https://goreportcard.com/report/github.com/wilhelm-murdoch/go-watcher)
+[![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)
+
+A no-nonsense wrapper around the [fsnotify](https://pkg.go.dev/github.com/fsnotify/fsnotify) package.
+
+## Install
+```
+$ go get github.com/wilhelm-murdoch/go-watcher
+```
+
+# Reference
+
+{{ range . }}{{ range .Files.Items }}{{ range .Functions.Items }}{{ if and (.IsExported) (ne .Name "main") (not .IsTest) (not .IsExample) (not .IsBenchmark)}}* [{{ .Name }}](#Function-{{ .Name }})
+{{ end }}{{ end }}{{ end }}{{ end }}
+
+{{ range . }}{{ range .Files.Items }}{{ $path := .Path }}{{ range .Functions.Items }}{{ if and (.IsExported) (ne .Name "main") (not .IsTest) (not .IsExample) (not .IsBenchmark)}}### Function `{{ .Name }}`
+* `{{ trim .Signature }}` [#]({{ $path }}#L{{ .LineStart }})
+* `{{ $path }}:{{ .LineStart }}:{{ .LineEnd }}` [#]({{ $path }}#L{{ .LineStart }}-L{{ .LineEnd }})
+
+{{ .Doc | replace "\n" " " }}
+{{ range .Examples.Items }}
+```go
+package main
+
+import (
+  "fmt"
+  "strings"
+
+  "github.com/wilhelm-murdoch/go-play"
+)
+
+func main() {
+{{ indent 4 .Body }}
+}
+```
+{{ if .Output }}```go
+{{ .Output }}
+```{{ end }}{{ end }}
+{{ end }}{{ end }}{{ end }}{{ end }}
+
+Documentation generated by [Gadget](https://github.com/wilhelm-murdoch/go-gadget).
+
+# License
+Copyright © {{ now | date "2006" }} [Wilhelm Murdoch](https://wilhelm.codes).
+
+This project is [MIT](./LICENSE) licensed.

watcher.go

@@ -153,9 +153,6 @@ func (w *Watcher) Watch() error {
 				w.fsnotify.Close()
 				close(w.done)
 				return nil
-
-			case err := <-w.fsnotify.Errors:
-				return err
 			}
 		}
 	})

watcher_example_test.go

@@ -0,0 +1,5 @@
+package watcher_test
+
+func ExampleWatcher_Watch_all() {
+
+}