feat: add documentations

chikador/api.go

@@ -15,6 +15,12 @@ type Message struct {
 	Error    error
 }
 
+// Watch creates a new Chismis instance that is watching over the given path, and its subdirectories if Recursive is
+// enabled. You can add the following options to give more power to the file watching capabilities:
+//
+// * Recursive: adds all the subdirectories under the directory and the subdirectories' subdirectories' subdirectories' sub.... you get it.
+//
+// * WithDedupe: (recommended) dedupes events which operating systems tend to have, this uses the implementation from fsnotify's own repository.
 func Watch(path string, opts ...Option) (*Chismis, error) {
 	watcher, err := fsnotify.NewWatcher()
 	if err != nil {
@@ -45,10 +51,21 @@ func Watch(path string, opts ...Option) (*Chismis, error) {
 	return chismis, nil
 }
 
+// Poll tries to poll data from the event queue, if there is none then it will return a nil pointer.
+// Recommended to use in a forever for-loop to continuously poll data. Alternatively, you can use Listen which is the
+// same as a for-loop, but asynchronous and shorter.
+//
+// Do note that you shouldn't have this twice, nor should you also use Listen if you are already polling data with this
+// method as the two methods will battle it out over who has the resource.
 func (chismis *Chismis) Poll() *Message {
 	return chismis.queue.poll()
 }
 
+// Listen listens to events from the event queue, this is running in another goroutine and uses the same polling method
+// internally.
+//
+// Do note that you shouldn't listen to a Chismis instance twice, only one listener ever, not even Poll, as this will
+// result in the resource being contended.
 func (chismis *Chismis) Listen(fn func(msg *Message)) {
 	go func() {
 		for {
@@ -61,6 +78,7 @@ func (chismis *Chismis) Listen(fn func(msg *Message)) {
 	}()
 }
 
+// Close removes all watches and closes all event channels.
 func (chismis *Chismis) Close() error {
 	return chismis.watcher.Close()
 }

chikador/api_options.go

@@ -8,14 +8,19 @@ type options struct {
 type watcherKind func(chismis *Chismis)
 type Option func(options *options)
 
+// Recursive will make chikador scan through the directory and its subdirectories to add to the file watcher.
 var Recursive = func(options *options) {
 	options.recursive = true
 }
 
+// WithDedupe enables deduping of events. As operating systems tends to duplicate events around and give you
+// "unnecessary noise", for most cases, it is recommended to enable this unless you need those "unnecessary noise".
 var WithDedupe = func(options *options) {
 	options.kind = withDedupe
 }
 
+// WithoutDedupe explicitly states that the Chismis instance shouldn't dedupe events, this is the default behavior, and
+// this is only added for completeness and when you want to explicitly indicate the behavior.
 var WithoutDedupe = func(options *options) {
 	options.kind = withoutDedupe
 }

chikador/core_watcher.go

@@ -6,6 +6,8 @@ import (
 	"path/filepath"
 )
 
+// add scans through the directory for more directories than adds those directories before scanning
+// for more subdirectories.
 func add(path string, watcher *fsnotify.Watcher) error {
 	files, err := os.ReadDir(path)
 	if err != nil {