From da276024cb812285c4134867f413374420d4e04d Mon Sep 17 00:00:00 2001
From: Justin Chadwell <me@jedevc.com>
Date: Mon, 7 Aug 2023 17:29:49 +0100
Subject: [PATCH] fs: improve docs for fs structs and functions

Signed-off-by: Justin Chadwell <me@jedevc.com>
---
 filter.go | 26 +++++++++++++++++++++++---
 fs.go     |  1 +
 2 files changed, 24 insertions(+), 3 deletions(-)

diff --git a/filter.go b/filter.go
index a73c06c..05f4a46 100644
--- a/filter.go
+++ b/filter.go
@@ -15,12 +15,22 @@ import (
 )
 
 type FilterOpt struct {
+	// IncludePatterns requires that the path matches at least one of the
+	// specified patterns.
 	IncludePatterns []string
+
+	// ExcludePatterns requires that the path does not match any of the
+	// specified patterns.
 	ExcludePatterns []string
-	// FollowPaths contains symlinks that are resolved into include patterns
-	// before performing the fs walk
+
+	// FollowPaths contains symlinks that are resolved into IncludePatterns
+	// at the time of the call to NewFilterFS.
 	FollowPaths []string
-	Map         MapFunc
+
+	// Map is called for each path that is included in the result.
+	// The function can modify the stat info for each element, while the result
+	// of the function controls both how Walk continues.
+	Map MapFunc
 }
 
 type MapFunc func(string, *types.Stat) MapResult
@@ -54,6 +64,16 @@ type filterFS struct {
 	mapFn MapFunc
 }
 
+// NewFilterFS creates a new FS that filters the given FS using the given
+// FilterOpt.
+
+// The returned FS will not contain any paths that do not match the provided
+// include and exclude patterns, or that are are exlcluded using the mapping
+// function.
+//
+// The FS is assumed to be a snapshot of the filesystem at the time of the
+// call to NewFilterFS. If the underlying filesystem changes, calls to the
+// underlying FS may be inconsistent.
 func NewFilterFS(fs FS, opt *FilterOpt) (FS, error) {
 	if opt == nil {
 		return fs, nil
diff --git a/fs.go b/fs.go
index 252278c..fe37019 100644
--- a/fs.go
+++ b/fs.go
@@ -21,6 +21,7 @@ type FS interface {
 	Open(string) (io.ReadCloser, error)
 }
 
+// NewFS creates a new FS from a root directory on the host filesystem.
 func NewFS(root string) (FS, error) {
 	root, err := filepath.EvalSymlinks(root)
 	if err != nil {