From 3bb909ba4f161c14e7fd9b231ad7b18daff114ab Mon Sep 17 00:00:00 2001 From: john Date: Sat, 6 Feb 2021 11:42:58 +0800 Subject: [PATCH] improve comment for package gspath --- os/gspath/gspath.go | 44 +++++++++++++++++------------------ os/gspath/gspath_unit_test.go | 5 ++++ 2 files changed, 27 insertions(+), 22 deletions(-) diff --git a/os/gspath/gspath.go b/os/gspath/gspath.go index c628968d8..d17ce2658 100644 --- a/os/gspath/gspath.go +++ b/os/gspath/gspath.go @@ -59,7 +59,7 @@ func New(path string, cache bool) *SPath { } // Get creates and returns a instance of searching manager for given path. -// The parameter specifies whether using cache feature for this manager. +// The parameter `cache` specifies whether using cache feature for this manager. // If cache feature is enabled, it asynchronously and recursively scans the path // and updates all sub files/folders to the cache using package gfsnotify. func Get(root string, cache bool) *SPath { @@ -71,24 +71,24 @@ func Get(root string, cache bool) *SPath { }).(*SPath) } -// Search searches file under path . -// The parameter should be a absolute path. It will not automatically -// convert to absolute path for performance reason. -// The optional parameter specifies the searching index files when the result is a directory. -// For example, if the result is a directory, and is [index.html, main.html], it will also -// search [index.html, main.html] under . It returns the absolute file path if any of them found, -// or else it returns . +// Search searches file `name` under path `root`. +// The parameter `root` should be a absolute path. It will not automatically +// convert `root` to absolute path for performance reason. +// The optional parameter `indexFiles` specifies the searching index files when the result is a directory. +// For example, if the result `filePath` is a directory, and `indexFiles` is [index.html, main.html], it will also +// search [index.html, main.html] under `filePath`. It returns the absolute file path if any of them found, +// or else it returns `filePath`. func Search(root string, name string, indexFiles ...string) (filePath string, isDir bool) { return Get(root, false).Search(name, indexFiles...) } -// SearchWithCache searches file under path with cache feature enabled. -// The parameter should be a absolute path. It will not automatically -// convert to absolute path for performance reason. -// The optional parameter specifies the searching index files when the result is a directory. -// For example, if the result is a directory, and is [index.html, main.html], it will also -// search [index.html, main.html] under . It returns the absolute file path if any of them found, -// or else it returns . +// SearchWithCache searches file `name` under path `root` with cache feature enabled. +// The parameter `root` should be a absolute path. It will not automatically +// convert `root` to absolute path for performance reason. +// The optional parameter `indexFiles` specifies the searching index files when the result is a directory. +// For example, if the result `filePath` is a directory, and `indexFiles` is [index.html, main.html], it will also +// search [index.html, main.html] under `filePath`. It returns the absolute file path if any of them found, +// or else it returns `filePath`. func SearchWithCache(root string, name string, indexFiles ...string) (filePath string, isDir bool) { return Get(root, true).Search(name, indexFiles...) } @@ -156,11 +156,11 @@ func (sp *SPath) Add(path string) (realPath string, err error) { } } -// Search searches file in the manager. -// The optional parameter specifies the searching index files when the result is a directory. -// For example, if the result is a directory, and is [index.html, main.html], it will also -// search [index.html, main.html] under . It returns the absolute file path if any of them found, -// or else it returns . +// Search searches file `name` in the manager. +// The optional parameter `indexFiles` specifies the searching index files when the result is a directory. +// For example, if the result `filePath` is a directory, and `indexFiles` is [index.html, main.html], it will also +// search [index.html, main.html] under `filePath`. It returns the absolute file path if any of them found, +// or else it returns `filePath`. func (sp *SPath) Search(name string, indexFiles ...string) (filePath string, isDir bool) { // No cache enabled. if sp.cache == nil { @@ -213,8 +213,8 @@ func (sp *SPath) Search(name string, indexFiles ...string) (filePath string, isD return } -// Remove deletes the from cache files of the manager. -// The parameter can be either a absolute path or just a relative file name. +// Remove deletes the `path` from cache files of the manager. +// The parameter `path` can be either a absolute path or just a relative file name. func (sp *SPath) Remove(path string) { if sp.cache == nil { return diff --git a/os/gspath/gspath_unit_test.go b/os/gspath/gspath_unit_test.go index 32cc09218..94b741337 100644 --- a/os/gspath/gspath_unit_test.go +++ b/os/gspath/gspath_unit_test.go @@ -90,22 +90,27 @@ func TestSPath_Basic(t *testing.T) { realPath, err = gsp.Add("gf_tmp1") t.Assert(err != nil, false) t.Assert(realPath, gfile.Join(root, "gf_tmp1")) + realPath, err = gsp.Add("gf_tmp3") t.Assert(err != nil, true) t.Assert(realPath, "") + gsp.Remove(gfile.Join(root, "gf_tmp")) gsp.Remove(gfile.Join(root, "gf_tmp1")) gsp.Remove(gfile.Join(root, "gf_tmp3")) t.Assert(gsp.Size(), 3) t.Assert(len(gsp.Paths()), 3) + gsp.AllPaths() gsp.Set(root) fp, isDir = gsp.Search("gf_tmp") t.Assert(fp, gfile.Join(root, "gf_tmp")) t.Assert(isDir, true) + fp, isDir = gsp.Search("gf_tmp", "gf.txt") t.Assert(fp, gfile.Join(root, "gf_tmp", "gf.txt")) t.Assert(isDir, false) + fp, isDir = gsp.Search("/", "gf.txt") t.Assert(fp, pwd) t.Assert(isDir, true)