comment updates for gfile

g/os/gfile/gfile.go

@@ -27,23 +27,20 @@ import (
 )
 
 const (
-    // 文件分隔符
+    // Separator for file system.
     Separator     = string(filepath.Separator)
-    // 默认的文件打开权限
+    // Default perm for file opening.
     gDEFAULT_PERM = 0666
 )
 
 var (
-    // 源码的main包所在目录，仅仅会设置一次
-    mainPkgPath   = gtype.NewString()
-
-    // 编译时的 GOROOT 数值
-    goRootOfBuild = gtype.NewString()
+    // The absolute file path for main package.
+    // It can be only checked and set once.
+    mainPkgPath = gtype.NewString()
 )
 
-// Create directories recursively.
-//
-// 给定目录的绝对路径创建目录(递归创建)。
+// Mkdir creates directories recursively with given <path>.
+// The parameter <path> is suggested to be absolute path.
 func Mkdir(path string) error {
     err  := os.MkdirAll(path, os.ModePerm)
     if err != nil {
@@ -52,9 +49,8 @@ func Mkdir(path string) error {
     return nil
 }
 
-// Create file with given path recursively.
-//
-// 给定文件的绝对路径创建文件。
+// Create creates file with given <path> recursively.
+// The parameter <path> is suggested to be absolute path.
 func Create(path string) (*os.File, error) {
     dir := Dir(path)
     if !Exists(dir) {
@@ -63,23 +59,17 @@ func Create(path string) (*os.File, error) {
     return os.Create(path)
 }
 
-// Open file/directory with readonly.
-//
-// 只读打开文件
+// Open opens file/directory readonly.
 func Open(path string) (*os.File, error) {
     return os.Open(path)
 }
 
-// Open file/directory with given <flag> and <perm>.
-//
-// 打开文件(带flag&perm)
+// OpenFile opens file/directory with given <flag> and <perm>.
 func OpenFile(path string, flag int, perm os.FileMode) (*os.File, error) {
     return os.OpenFile(path, flag, perm)
 }
 
-// Open file/directory with default perm and given <flag>.
-//
-// 打开文件(带flag)
+// OpenWithFlag opens file/directory with default perm and given <flag>.
 func OpenWithFlag(path string, flag int) (*os.File, error) {
     f, err  := os.OpenFile(path, flag, gDEFAULT_PERM)
     if err != nil {
@@ -88,9 +78,7 @@ func OpenWithFlag(path string, flag int) (*os.File, error) {
     return f, nil
 }
 
-// Open file/directory with given <flag> and <perm>.
-//
-// 打开文件(带flag&perm)
+// OpenWithFlagPerm opens file/directory with given <flag> and <perm>.
 func OpenWithFlagPerm(path string, flag int, perm int) (*os.File, error) {
     f, err  := os.OpenFile(path, flag, os.FileMode(perm))
     if err != nil {
@@ -99,9 +87,7 @@ func OpenWithFlagPerm(path string, flag int, perm int) (*os.File, error) {
     return f, nil
 }
 
-// Check whether given path exist.
-//
-// 判断所给路径文件/文件夹是否存在
+// Exists checks whether given <path> exist.
 func Exists(path string) bool {
     if _, err := os.Stat(path); !os.IsNotExist(err) {
         return true
@@ -109,9 +95,7 @@ func Exists(path string) bool {
     return false
 }
 
-// Check whether given path a directory.
-//
-// 判断所给路径是否为文件夹
+// IsDir checks whether given <path> a directory.
 func IsDir(path string) bool {
     s, err := os.Stat(path)
     if err != nil {
@@ -120,17 +104,13 @@ func IsDir(path string) bool {
     return s.IsDir()
 }
 
-// Get current working directory absolute path.
-//
-// 获取当前工作目录(注意与SelfDir的区别).
+// Pwd returns absolute path of current working directory.
 func Pwd() string {
     path, _ := os.Getwd()
     return path
 }
 
-// Check whether given path a file(not a directory).
-//
-// 判断所给路径是否为文件
+// IsFile checks whether given <path> a file, which means it's not a directory.
 func IsFile(path string) bool {
     s, err := os.Stat(path)
     if err != nil {
@@ -139,39 +119,32 @@ func IsFile(path string) bool {
     return !s.IsDir()
 }
 
+// Alias of Stat.
 // See Stat.
-//
-// Stat 方法的别名。
 func Info(path string) (os.FileInfo, error) {
     return Stat(path)
 }
 
 // Stat returns a FileInfo describing the named file.
 // If there is an error, it will be of type *PathError.
-//
-// 获取文件或目录信息.
 func Stat(path string) (os.FileInfo, error) {
     return os.Stat(path)
 }
 
-// Move renames (moves) src to dst path.
-//
-// 文件移动/重命名
+// Move renames (moves) <src> to <dst> path.
 func Move(src string, dst string) error {
     return os.Rename(src, dst)
 }
 
-// Rename renames (moves) src to dst path.
-//
-// 文件移动/重命名.
+// Alias of Move.
+// See Move.
 func Rename(src string, dst string) error {
     return Move(src, dst)
 }
 
-// Copy file from src to dst.
+// Copy file from <src> to <dst>.
 //
-// 文件复制.
-// @TODO 支持目录复制.
+// @TODO directory copy support.
 func Copy(src string, dst string) error {
     srcFile, err := Open(src)
     if err != nil {
@@ -194,9 +167,7 @@ func Copy(src string, dst string) error {
     return nil
 }
 
-// Get sub-file names of path.
-//
-// 返回目录下的文件名列表
+// DirNames returns sub-file names of given directory <path>.
 func DirNames(path string) ([]string, error) {
     f, err := os.Open(path)
     if err != nil {
@@ -218,8 +189,6 @@ func DirNames(path string) ([]string, error) {
 // Glob ignores file system errors such as I/O errors reading directories.
 // The only possible returned error is ErrBadPattern, when pattern
 // is malformed.
-//
-// 文件名正则匹配查找，第二个可选参数指定返回的列表是否仅为文件名(非绝对路径)，默认返回绝对路径
 func Glob(pattern string, onlyNames...bool) ([]string, error) {
     if list, err := filepath.Glob(pattern); err == nil {
         if len(onlyNames) > 0 && onlyNames[0] && len(list) > 0 {
@@ -235,16 +204,13 @@ func Glob(pattern string, onlyNames...bool) ([]string, error) {
     }
 }
 
-// Remove file/directory with <path> parameter.
-//
-// 文件/目录删除
+// Remove deletes all file/directory with <path> parameter.
+// If parameter <path> is directory, it deletes it recursively.
 func Remove(path string) error {
     return os.RemoveAll(path)
 }
 
-// Check whether given <path> is readable.
-//
-// 文件是否可读(支持文件/目录)
+// IsReadable checks whether given <path> is readable.
 func IsReadable(path string) bool {
     result    := true
     file, err := os.OpenFile(path, os.O_RDONLY, gDEFAULT_PERM)
@@ -255,14 +221,13 @@ func IsReadable(path string) bool {
     return result
 }
 
-// Check whether given <path> is writable.
+// IsWritable checks whether given <path> is writable.
 //
-// 文件是否可写(支持文件/目录)
-// @TODO 改进性能，利用 golang.org/x/sys 来实现跨平台的权限判断。
+// @TODO improve performance; use golang.org/x/sys to cross-plat-form
 func IsWritable(path string) bool {
     result := true
     if IsDir(path) {
-        // 如果是目录，那么创建一个临时文件进行写入测试
+        // If it's a directory, create a temporary file to test whether it's writable.
         tmpFile := strings.TrimRight(path, Separator) + Separator + gconv.String(time.Now().UnixNano())
         if f, err := Create(tmpFile); err != nil || !Exists(tmpFile){
             result = false
@@ -282,16 +247,12 @@ func IsWritable(path string) bool {
 }
 
 // See os.Chmod.
-//
-// 修改文件/目录权限
 func Chmod(path string, mode os.FileMode) error {
     return os.Chmod(path, mode)
 }
 
-// Get all sub-files(absolute) of given <path>,
-// can be recursively with given parameter <recursive> true.
-//
-// 打开目录，并返回其下一级文件列表(绝对路径)，按照文件名称大小写进行排序，支持目录递归遍历。
+// ScanDir returns all sub-files with absolute paths of given <path>,
+// It scans directory recursively if given parameter <recursive> is true.
 func ScanDir(path string, pattern string, recursive ... bool) ([]string, error) {
     list, err := doScanDir(path, pattern, recursive...)
     if err != nil {
@@ -303,22 +264,24 @@ func ScanDir(path string, pattern string, recursive ... bool) ([]string, error)
     return list, nil
 }
 
-// 内部检索目录方法，支持递归，返回没有排序的文件绝对路径列表结果。
-// pattern参数支持多个文件名称模式匹配，使用','符号分隔多个模式。
+// doScanDir is an internal method which scans directory
+// and returns the absolute path list of files that are not sorted.
+//
+// The pattern parameter <pattern> supports multiple file name patterns,
+// using the ',' symbol to separate multiple patterns.
+//
+// It scans directory recursively if given parameter <recursive> is true.
 func doScanDir(path string, pattern string, recursive ... bool) ([]string, error) {
     list := ([]string)(nil)
-    // 打开目录
     file, err := os.Open(path)
     if err != nil {
         return nil, err
     }
     defer file.Close()
-    // 读取目录下的文件列表
     names, err := file.Readdirnames(-1)
     if err != nil {
         return nil, err
     }
-    // 是否递归遍历
     for _, name := range names {
         path := fmt.Sprintf("%s%s%s", path, Separator, name)
         if IsDir(path) && len(recursive) > 0 && recursive[0] {
@@ -327,7 +290,7 @@ func doScanDir(path string, pattern string, recursive ... bool) ([]string, error
                 list = append(list, array...)
             }
         }
-        // 满足pattern才加入结果列表
+        // If it meets pattern, then add it to the result list.
         for _, p := range strings.Split(pattern, ",") {
             if match, err := filepath.Match(strings.TrimSpace(p), name); err == nil && match {
                 list = append(list, path)
@@ -337,10 +300,9 @@ func doScanDir(path string, pattern string, recursive ... bool) ([]string, error
     return list, nil
 }
 
-// See filepath.Abs.
-//
-// 将所给定的路径转换为绝对路径
-// 并判断文件路径是否存在，如果文件不存在，那么返回空字符串
+// RealPath converts the given <path> to its absolute path
+// and checks if the file path exists.
+// If the file does not exist, return an empty string.
 func RealPath(path string) string {
     p, err := filepath.Abs(path)
     if err != nil {
@@ -352,45 +314,46 @@ func RealPath(path string) string {
     return p
 }
 
-// Get absolute file path of current running process(binary).
-//
-// 获取当前执行文件的绝对路径
+// SelfPath returns absolute file path of current running process(binary).
 func SelfPath() string {
     p, _ := filepath.Abs(os.Args[0])
     return p
 }
 
-// Get absolute directory path of current running process(binary).
-//
-// 获取当前执行文件的目录绝对路径
+// SelfDir returns absolute directory path of current running process(binary).
 func SelfDir() string {
     return filepath.Dir(SelfPath())
 }
 
-// See filepath.Base.
-//
-// 获取指定文件路径的文件名称
+// Basename returns the last element of path.
+// Trailing path separators are removed before extracting the last element.
+// If the path is empty, Base returns ".".
+// If the path consists entirely of separators, Base returns a single separator.
 func Basename(path string) string {
     return filepath.Base(path)
 }
 
-// See filepath.Dir.
-//
-// 获取指定文件路径的目录地址绝对路径.
+// Dir returns all but the last element of path, typically the path's directory.
+// After dropping the final element, Dir calls Clean on the path and trailing
+// slashes are removed.
+// If the path is empty, Dir returns ".".
+// If the path consists entirely of separators, Dir returns a single separator.
+// The returned path does not end in a separator unless it is the root directory.
 func Dir(path string) string {
     return filepath.Dir(path)
 }
 
-// See filepath.Ext.
+// Ext returns the file name extension used by path.
+// The extension is the suffix beginning at the final dot
+// in the final element of path; it is empty if there is
+// no dot.
 //
-// 获取指定文件路径的文件扩展名(包含"."号)
+// Note: the result contains symbol '.'.
 func Ext(path string) string {
     return filepath.Ext(path)
 }
 
-// Get absolute home directory path of current user.
-//
-// 获取用户主目录
+// Home returns absolute path of current user's home directory.
 func Home() (string, error) {
     u, err := user.Current()
     if nil == err {
@@ -435,12 +398,15 @@ func homeWindows() (string, error) {
     return home, nil
 }
 
-// Get absolute file path of main file, which contains the entrance function main.
-// Available in develop environment.
+// MainPkgPath returns absolute file path of package main,
+// which contains the entrance function main.
 //
-// 获取入口函数文件所在目录(main包文件目录),
-// **仅对源码开发环境有效(即仅对生成该可执行文件的系统下有效)**。
-// 注意：该方法被第一次调用时，如果是在异步的goroutine中，该方法可能无法获取到main包路径。
+// It's only available in develop environment.
+//
+// Note1: Only valid for source development environments,
+// IE only valid for systems that generate this executable.
+// Note2: When the method is called for the first time, if it is in an asynchronous goroutine,
+// the method may not get the main package path.
 func MainPkgPath() string {
     path := mainPkgPath.Val()
     if path != "" {
@@ -473,14 +439,13 @@ func MainPkgPath() string {
             break
         }
     }
-    // 找不到，下次不用再检索了
+    // If it fails finding the path, then mark it as "-",
+    // which means it will never do this search again.
 	mainPkgPath.Set("-")
     return ""
 }
 
 // See os.TempDir().
-//
-// 系统临时目录
 func TempDir() string {
     return os.TempDir()
 }