improve comments and tests

Author: wxiaoguang

modules/util/path.go

@@ -14,17 +14,17 @@ import (
 	"strings"
 )
 
-// SafePathRel joins the path elements into a single path, each element is cleaned separately
-// It only returns the following values (like path.Join):
+// SafePathRel joins the path elements into a single path, each element is cleaned by path.Clean separately.
+// It only returns the following values (like path.Join), any redundant part (empty, relative dots, slashes) is removed.
 //
 //	empty => ``
 //	`` => ``
 //	`..` => `.`
 //	`dir` => `dir`
 //	`/dir/` => `dir`
 //	`foo\..\bar` => `foo\..\bar`
-//
-// any redundant part(relative dots, slashes) is removed.
+//	{`foo`, ``, `bar`} => `foo/bar`
+//	{`foo`, `..`, `bar`} => `foo/bar`
 func SafePathRel(elem ...string) string {
 	elems := make([]string, len(elem))
 	for i, e := range elem {
@@ -44,12 +44,12 @@ func SafePathRel(elem ...string) string {
 }
 
 // SafePathRelX joins the path elements into a single path like SafePathRel,
-// and covert all backslashes to slashes. (X means "extended", also means the combination of `\` and `/`)
+// and covert all backslashes to slashes. (X means "extended", also means the combination of `\` and `/`).
 // It returns similar results as SafePathRel except:
 //
 //	`foo\..\bar` => `bar`  (because it's processed as `foo/../bar`)
 //
-// any redundant part(relative dots, slashes) is removed.
+// All backslashes are handled as slashes, the result only contains slashes.
 func SafePathRelX(elem ...string) string {
 	elems := make([]string, len(elem))
 	for i, e := range elem {
@@ -63,9 +63,13 @@ func SafePathRelX(elem ...string) string {
 
 const pathSeparator = string(os.PathSeparator)
 
-// SafeFilePathAbs joins the path elements into a single file path, each element is cleaned separately
-// and convert all slashes/backslashes to path separators.
-// The first element must be an absolute path, caller should prepare the base path
+// SafeFilePathAbs joins the path elements into a single file path, each element is cleaned by filepath.Clean separately.
+// All slashes/backslashes are converted to path separators before cleaning, the result only contains path separators.
+// The first element must be an absolute path, caller should prepare the base path.
+// Like SafePathRel, any redundant part (empty, relative dots, slashes) is removed.
+//
+//	{`/foo`, ``, `bar`} => `/foo/bar`
+//	{`/foo`, `..`, `bar`} => `/foo/bar`
 func SafeFilePathAbs(elem ...string) string {
 	elems := make([]string, len(elem))
 

modules/util/path_test.go

@@ -149,6 +149,8 @@ func TestCleanPath(t *testing.T) {
 		{[]string{`/a/`}, `a`},
 		{[]string{`../a/`, `../b`, `c/..`, `d`}, `a/b/d`},
 		{[]string{`a\..\b`}, `a\..\b`},
+		{[]string{`a`, ``, `b`}, `a/b`},
+		{[]string{`a`, `..`, `b`}, `a/b`},
 	}
 	for _, c := range cases {
 		assert.Equal(t, c.expected, SafePathRel(c.elems...), "case: %v", c.elems)
@@ -165,6 +167,8 @@ func TestCleanPath(t *testing.T) {
 		{[]string{`/a/`}, `a`},
 		{[]string{`../a/`, `../b`, `c/..`, `d`}, `a/b/d`},
 		{[]string{`a\..\b`}, `b`},
+		{[]string{`a`, ``, `b`}, `a/b`},
+		{[]string{`a`, `..`, `b`}, `a/b`},
 	}
 	for _, c := range cases {
 		assert.Equal(t, c.expected, SafePathRelX(c.elems...), "case: %v", c.elems)
@@ -181,6 +185,8 @@ func TestCleanPath(t *testing.T) {
 			{[]string{`C:\a/`}, `C:\a`},
 			{[]string{`C:\..\a\`, `../b`, `c\..`, `d`}, `C:\a\b\d`},
 			{[]string{`C:\a/..\b`}, `C:\b`},
+			{[]string{`C:\a`, ``, `b`}, `C:\a\b`},
+			{[]string{`C:\a`, `..`, `b`}, `C:\a\b`},
 		}
 	} else {
 		cases = []struct {
@@ -192,6 +198,8 @@ func TestCleanPath(t *testing.T) {
 			{[]string{`/a/`}, `/a`},
 			{[]string{`/../a/`, `../b`, `c/..`, `d`}, `/a/b/d`},
 			{[]string{`/a\..\b`}, `/b`},
+			{[]string{`/a`, ``, `b`}, `/a/b`},
+			{[]string{`/a`, `..`, `b`}, `/a/b`},
 		}
 	}
 	for _, c := range cases {