From 6fa8eea5e2bdc27f937d94af42add406dbdce1f4 Mon Sep 17 00:00:00 2001
From: sammyette <torchedsammy@gmail.com>
Date: Sun, 22 Dec 2024 12:39:15 -0400
Subject: [PATCH] docs: document fs watcher

---
 golibs/fs/fs.go      |  6 ++++++
 golibs/fs/watcher.go | 26 +++++++++++++++++---------
 2 files changed, 23 insertions(+), 9 deletions(-)

diff --git a/golibs/fs/fs.go b/golibs/fs/fs.go
index 4c209de..6c11e31 100644
--- a/golibs/fs/fs.go
+++ b/golibs/fs/fs.go
@@ -329,6 +329,12 @@ func fstat(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.PushingNext1(t.Runtime, rt.TableValue(statTbl)), nil
 }
 
+// watch(path, callback)
+// Watches a path for changes made to it. For example, to monitor
+// new files created in a folder.
+// The callback passed 2 string arguments, the `event` and the absolute `path`
+// #param path string
+// #param callback function
 func fwatch(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	if err := c.CheckNArgs(2); err != nil {
 		return nil, err
diff --git a/golibs/fs/watcher.go b/golibs/fs/watcher.go
index 8a8ce23..f4f34ab 100644
--- a/golibs/fs/watcher.go
+++ b/golibs/fs/watcher.go
@@ -7,7 +7,9 @@ import (
 	rt "github.com/arnodel/golua/runtime"
 )
 
-type pathWatcher struct{
+// #type
+// Watcher type describes a `fs` library file watcher.
+type watcher struct{
 	path string
 	callback *rt.Closure
 	paused bool
@@ -16,7 +18,7 @@ type pathWatcher struct{
 	notifyChan chan notify.EventInfo
 }
 
-func (w *pathWatcher) start() {
+func (w *watcher) start() {
 	if w.callback == nil || w.started {
 		return
 	}
@@ -38,11 +40,14 @@ func (w *pathWatcher) start() {
 	}()
 }
 
-func (w *pathWatcher) stop() {
+func (w *watcher) stop() {
 	w.started = false
 	notify.Stop(w.notifyChan)
 }
 
+// #member
+// start()
+// Start/resume file watching.
 func watcherStart(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	pw, err := watcherArg(c, 0)
 	if err != nil {
@@ -54,6 +59,9 @@ func watcherStart(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
+// #member
+// stop()
+// Stops watching for changes. Effectively ignores changes.
 func watcherStop(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	pw, err := watcherArg(c, 0)
 	if err != nil {
@@ -65,8 +73,8 @@ func watcherStop(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
 	return c.Next(), nil
 }
 
-func newWatcher(path string, callback *rt.Closure) *pathWatcher {
-	pw := &pathWatcher{
+func newWatcher(path string, callback *rt.Closure) *watcher {
+	pw := &watcher{
 		path: path,
 		callback: callback,
 	}
@@ -76,7 +84,7 @@ func newWatcher(path string, callback *rt.Closure) *pathWatcher {
 	return pw
 }
 
-func watcherArg(c *rt.GoCont, arg int) (*pathWatcher, error) {
+func watcherArg(c *rt.GoCont, arg int) (*watcher, error) {
 	j, ok := valueToWatcher(c.Arg(arg))
 	if !ok {
 		return nil, fmt.Errorf("#%d must be a watcher", arg + 1)
@@ -85,17 +93,17 @@ func watcherArg(c *rt.GoCont, arg int) (*pathWatcher, error) {
 	return j, nil
 }
 
-func valueToWatcher(val rt.Value) (*pathWatcher, bool) {
+func valueToWatcher(val rt.Value) (*watcher, bool) {
 	u, ok := val.TryUserData()
 	if !ok {
 		return nil, false
 	}
 
-	j, ok := u.Value().(*pathWatcher)
+	j, ok := u.Value().(*watcher)
 	return j, ok
 }
 
-func watcherUserData(j *pathWatcher) *rt.UserData {
+func watcherUserData(j *watcher) *rt.UserData {
 	watcherMeta := rtmm.Registry(watcherMetaKey)
 	return rt.NewUserData(j, watcherMeta.AsTable())
 }