update comments

filecache.go

@@ -76,11 +76,13 @@ type FileCache interface {
 	WriteData(ctx context.Context, key string, data []byte, options ...ItemOptions) (written int64, err error)
 
 	// Open opens the reader with cached data.
+	//
 	// Returns no error on successful cache hit, on no hit, on invalid cache files.
 	// Returns an error if failed to open an existing cache file or if context is done.
 	Open(ctx context.Context, key string) (result *OpenResult, err error)
 
 	// Read reads data from the cache file.
+	//
 	// Returns no error on successful cache hit, on no hit, on invalid cache files.
 	// Returns an error if failed to open or read an existing cache file or if context is done.
 	Read(ctx context.Context, key string) (result *ReadResult, err error)

gc.go

@@ -20,12 +20,13 @@ func NewNopGarbageCollector() GarbageCollector {
 }
 
 // NewProbabilityGarbageCollector returns the GarbageCollector running with the defined probability.
-// Divisor is a run probability divisor (e.g., divisor equals 100 is a 1/100 probability).
 //
 // Function arguments:
-// * dir - the directory with the FileCache's instance files;
-// * onInitDivisor - divisor for the probability on the OnInstanceInit() function call;
-// * onOpDivisor - divisor for the probability on the OnOperation() function call.
+//   - dir: the directory with the FileCache's instance files;
+//   - onInitDivisor: divisor for the probability on the OnInstanceInit() function call;
+//   - onOpDivisor: divisor for the probability on the OnOperation() function call.
+//
+// Divisor is a run probability divisor (e.g., divisor equals 100 is a 1/100 probability).
 func NewProbabilityGarbageCollector(dir string, onInitDivisor uint, onOpDivisor uint) GarbageCollector {
 	return &gcProbability{
 		dir:           dir,
@@ -35,6 +36,10 @@ func NewProbabilityGarbageCollector(dir string, onInitDivisor uint, onOpDivisor
 }
 
 // NewIntervalGarbageCollector returns the GarbageCollector running by the interval.
+//
+// Function arguments:
+//   - dir: the directory with the FileCache's instance files;
+//   - interval: the GC interval duration.
 func NewIntervalGarbageCollector(dir string, interval time.Duration) GarbageCollector {
 	return &gcInterval{
 		dir:      dir,

options.go

@@ -5,12 +5,25 @@ import "time"
 // InstanceOptions are a cache instance options.
 type InstanceOptions struct {
 	// PathGenerator is a function to generate cache item's file path.
+	// Receives the key of the cache item and returns the path of the item relative to the cache instance's dir.
+	//
+	// There are some built-in path generators:
+	// 	 - FilteredKeyPath: removes path separators from the key and uses it as a file name;
+	//   - HashedKeyPath: hashes the key and uses the result as a file name;
+	//   - HashedKeySplitPath: hashes the key, splits result to the parts and uses them as a directories and file names.
+	//
+	// Also, there is a WithExt wrapper adding the extension to any path generator result.
 	PathGenerator PathGeneratorFn
 
 	// DefaultTTL is a TTL value for the items without it.
 	DefaultTTL time.Duration
 
 	// GC is a GarbageCollector instance for the cache instance.
+	//
+	// May be initialized with any GarbageCollector instance or using one of the predefined GC constructors:
+	//   - NewNopGarbageCollector: the GarbageCollector doing nothing;
+	//   - NewProbabilityGarbageCollector: the GarbageCollector running with the defined probability;
+	//   - NewIntervalGarbageCollector: the GarbageCollector running by the interval.
 	GC GarbageCollector
 
 	// GCDivisor is a garbage collector run probability divisor
@@ -20,7 +33,7 @@ type InstanceOptions struct {
 	GCDivisor uint
 }
 
-// ItemOptions are a cache item options
+// ItemOptions are a cache item options.
 type ItemOptions struct {
 	// Name is a human-readable item name.
 	Name string

paths.go

@@ -10,6 +10,7 @@ import (
 )
 
 // PathGeneratorFn is a function to generate cache item's file path.
+// Receives the key of the cache item and returns the path of the item relative to the cache instance's dir.
 type PathGeneratorFn func(key string) string
 
 // WithExt returns new PathGeneratorWithExt instance.
@@ -36,7 +37,7 @@ func FilteredKeyPath(key string) string {
 	return path
 }
 
-// HashedKeyPath return hashes key and uses it as a file name.
+// HashedKeyPath return hashed key and uses it as a file name.
 func HashedKeyPath(key string) string {
 	//nolint:gosec
 	h := sha1.New()