comment update for gfile/gaes/gcrc32/gdes/gmd5/gsha1

g/crypto/gaes/gaes.go

@@ -65,7 +65,6 @@ func Decrypt(cipherText []byte, key []byte, iv...[]byte) ([]byte, error) {
 	if e != nil {
 		return nil, e
 	}
-
     return plainText, nil
 }
 

g/crypto/gcrc32/gcrc32.go

@@ -4,17 +4,26 @@
 // If a copy of the MIT was not distributed with this file,
 // You can obtain one at https://github.com/gogf/gf.
 
-// Package gcrc32 provides useful API for CRC32 encryption/decryption algorithms.
+// Package gcrc32 provides useful API for CRC32 encryption algorithms.
 package gcrc32
 
 import (
-    "hash/crc32"
+	"github.com/gogf/gf/g/util/gconv"
+	"hash/crc32"
 )
 
+// Encrypt encrypts any type of variable using CRC32 algorithms.
+// It uses gconv package to convert <v> to its bytes type.
+func Encrypt(v interface{}) uint32 {
+	return crc32.ChecksumIEEE(gconv.Bytes(v))
+}
+
+// Deprecated.
 func EncryptString(v string) uint32 {
     return crc32.ChecksumIEEE([]byte(v))
 }
 
+// Deprecated.
 func EncryptBytes(v []byte) uint32 {
     return crc32.ChecksumIEEE(v)
 }

g/crypto/gdes/gdes.go

@@ -3,7 +3,8 @@
 // This Source Code Form is subject to the terms of the MIT License.
 // If a copy of the MIT was not distributed with this file,
 // You can obtain one at https://github.com/gogf/gf.
-// @author: wenzi1<liyz23@qq.com>
+//
+// @author wenzi1<liyz23@qq.com>
 
 // Package gdes provides useful API for DES encryption/decryption algorithms.
 package gdes
@@ -16,11 +17,11 @@ import (
 )
 
 const (
-	NOPADDING     = iota
+	NOPADDING    = iota
 	PKCS5PADDING
 )
 
-//ECB模式DES加密
+// ECB模式DES加密
 func DesECBEncrypt(key []byte, clearText []byte, padding int) ([]byte, error) {
 	text, err := Padding(clearText, padding)
 	if err != nil {
@@ -42,7 +43,7 @@ func DesECBEncrypt(key []byte, clearText []byte, padding int) ([]byte, error) {
 	return cipherText, nil
 }
 
-//ECB模式DES解密
+// ECB模式DES解密
 func DesECBDecrypt(key []byte, cipherText []byte, padding int) ([]byte, error) {
 	text := make([]byte, len(cipherText))
 	block, err := des.NewCipher(key)
@@ -63,7 +64,7 @@ func DesECBDecrypt(key []byte, cipherText []byte, padding int) ([]byte, error) {
 	return clearText, nil
 }
 
-//ECB模式3DES加密，密钥长度可以是16或24位长
+// ECB模式3DES加密，密钥长度可以是16或24位长
 func TripleDesECBEncrypt(key []byte, clearText []byte, padding int) ( []byte, error) {
 	if len(key) != 16 && len(key) != 24 {
 		return nil, errors.New("key length error")
@@ -96,7 +97,7 @@ func TripleDesECBEncrypt(key []byte, clearText []byte, padding int) ( []byte, er
 	return cipherText, nil
 }
 
-//ECB模式3DES解密，密钥长度可以是16或24位长
+// ECB模式3DES解密，密钥长度可以是16或24位长
 func TripleDesECBDecrypt(key []byte, cipherText []byte, padding int) ([]byte,  error) {
 	if len(key) != 16 && len(key) != 24 {
 		return nil, errors.New("key length error")
@@ -129,7 +130,7 @@ func TripleDesECBDecrypt(key []byte, cipherText []byte, padding int) ([]byte,  e
 	return clearText, nil
 }
 
-//CBC模式DES加密
+// CBC模式DES加密
 func DesCBCEncrypt(key []byte, clearText []byte, iv []byte, padding int) ([]byte, error) {
 	block, err := des.NewCipher(key)
 	if err != nil {
@@ -152,7 +153,7 @@ func DesCBCEncrypt(key []byte, clearText []byte, iv []byte, padding int) ([]byte
 	return cipherText, nil
 }
 
-//CBC模式DES解密
+// CBC模式DES解密
 func DesCBCDecrypt(key []byte, cipherText []byte, iv []byte, padding int) ([]byte, error) {
 	block, err := des.NewCipher(key)
 	if err != nil {
@@ -175,7 +176,7 @@ func DesCBCDecrypt(key []byte, cipherText []byte, iv []byte, padding int) ([]byt
 	return clearText, nil
 }
 
-//CBC模式3DES加密
+// CBC模式3DES加密
 func TripleDesCBCEncrypt(key []byte, clearText []byte, iv []byte, padding int) ([]byte, error) {
 	if len(key) != 16 && len(key) != 24 {
 		return nil, errors.New("key length invalid")
@@ -210,7 +211,7 @@ func TripleDesCBCEncrypt(key []byte, clearText []byte, iv []byte, padding int) (
 	return cipherText, nil
 }
 
-//CBC模式3DES解密
+// CBC模式3DES解密
 func TripleDesCBCDecrypt(key []byte, cipherText []byte, iv []byte, padding int) ( []byte,  error) {
 	if len(key) != 16 && len(key) != 24 {
 		return nil, errors.New("key length invalid")
@@ -245,21 +246,21 @@ func TripleDesCBCDecrypt(key []byte, cipherText []byte, iv []byte, padding int)
 	return clearText, nil
 }
 
-//PKCS5补位
+// PKCS5补位
 func PKCS5Padding(text []byte, blockSize int) []byte {
 	padding := blockSize - len(text) % blockSize
 	padtext := bytes.Repeat([]byte{byte(padding)}, padding)
 	return append(text, padtext...)
 }
 
-//去除PKCS5补位
+// 去除PKCS5补位
 func PKCS5Unpadding(text []byte) []byte{
 	length := len(text)
 	padtext := int(text[length - 1])
 	return text[:(length - padtext)]
 }
 
-//补位方法
+// 补位方法
 func Padding(text []byte, padding int)([]byte, error) {
 	switch padding {
 		case NOPADDING:
@@ -275,7 +276,7 @@ func Padding(text []byte, padding int)([]byte, error) {
 	return text, nil
 }
 
-//去除补位方法
+// 去除补位方法
 func UnPadding(text []byte, padding int)([]byte, error) {
 	switch padding {
 		case NOPADDING:

g/crypto/gmd5/gmd5.go

@@ -4,7 +4,7 @@
 // If a copy of the MIT was not distributed with this file,
 // You can obtain one at https://github.com/gogf/gf.
 
-// Package gmd5 provides useful API for MD5 encryption/decryption algorithms.
+// Package gmd5 provides useful API for MD5 encryption algorithms.
 package gmd5
 
 import (
@@ -15,28 +15,31 @@ import (
     "github.com/gogf/gf/g/util/gconv"
 )
 
-// 将任意类型的变量进行md5摘要(注意map等非排序变量造成的不同结果)
+// Encrypt encrypts any type of variable using MD5 algorithms.
+// It uses gconv package to convert <v> to its bytes type.
 func Encrypt(v interface{}) string {
     h := md5.New()
     h.Write([]byte(gconv.Bytes(v)))
     return fmt.Sprintf("%x", h.Sum(nil))
 }
 
-// 将字符串进行MD5哈希摘要计算
+
+// Deprecated.
 func EncryptString(v string) string {
-    h := md5.New()
-    h.Write([]byte(v))
-    return fmt.Sprintf("%x", h.Sum(nil))
+	h := md5.New()
+	h.Write([]byte(v))
+	return fmt.Sprintf("%x", h.Sum(nil))
 }
 
-// 将文件内容进行MD5哈希摘要计算
+
+// EncryptFile encrypts file content of <path> using MD5 algorithms.
 func EncryptFile(path string) string {
     f, e := os.Open(path)
     if e != nil {
         return ""
     }
     defer f.Close()
-    h := md5.New()
+    h   := md5.New()
     _, e = io.Copy(h, f)
     if e != nil {
         return ""

g/crypto/gsha1/gsha1.go

@@ -4,7 +4,7 @@
 // If a copy of the MIT was not distributed with this file,
 // You can obtain one at https://github.com/gogf/gf.
 
-// Package gsha1 provides useful API for SHA1 encryption/decryption algorithms.
+// Package gsha1 provides useful API for SHA1 encryption algorithms.
 package gsha1
 
 import (
@@ -15,20 +15,20 @@ import (
     "github.com/gogf/gf/g/util/gconv"
 )
 
-// 将任意类型的变量进行SHA摘要(注意map等非排序变量造成的不同结果)
-// 内部使用了md5计算，因此效率会稍微差一些，更多情况请使用 EncodeString
+// Encrypt encrypts any type of variable using SHA1 algorithms.
+// It uses gconv package to convert <v> to its bytes type.
 func Encrypt(v interface{}) string {
     r := sha1.Sum(gconv.Bytes(v))
     return hex.EncodeToString(r[:])
 }
 
-// 对字符串行SHA1摘要计算
+// Deprecated.
 func EncryptString(s string) string {
-    r := sha1.Sum([]byte(s))
-    return hex.EncodeToString(r[:])
+	r := sha1.Sum([]byte(s))
+	return hex.EncodeToString(r[:])
 }
 
-// 对文件内容进行SHA1摘要计算
+// EncryptFile encrypts file content of <path> using SHA1 algorithms.
 func EncryptFile(path string) string {
     f, e := os.Open(path)
     if e != nil {

g/os/gfile/gfile_contents.go

@@ -13,18 +13,18 @@ import (
 )
 
 const (
-    // 方法中涉及到读取的时候的缓冲大小
-    gREAD_BUFFER      = 1024
-    // 方法中涉及到文件指针池的默认缓存时间(毫秒)
-    //gFILE_POOL_EXPIRE = 60000
+    // Buffer size for reading file content.
+    gREAD_BUFFER = 1024
 )
 
-// (文本)读取文件内容
+// GetContents returns the file content of <path> as string.
+// It returns en empty string if it fails reading.
 func GetContents(path string) string {
     return string(GetBinContents(path))
 }
 
-// (二进制)读取文件内容，如果文件不存在或者读取失败，返回nil。
+// GetBinContents returns the file content of <path> as []byte.
+// It returns nil if it fails reading.
 func GetBinContents(path string) []byte {
     data, err := ioutil.ReadFile(path)
     if err != nil {
@@ -33,16 +33,16 @@ func GetBinContents(path string) []byte {
     return data
 }
 
-// 写入文件内容
+// putContents puts binary content to file of <path>.
 func putContents(path string, data []byte, flag int, perm int) error {
-    // 支持目录递归创建
+    // It supports creating file of <path> recursively.
     dir := Dir(path)
     if !Exists(dir) {
         if err := Mkdir(dir); err != nil {
             return err
         }
     }
-    // 创建/打开文件
+    // Opening file with given <flag> and <perm>.
     f, err := OpenWithFlagPerm(path, flag, perm)
     if err != nil {
         return err
@@ -56,32 +56,36 @@ func putContents(path string, data []byte, flag int, perm int) error {
     return nil
 }
 
-// Truncate
+// Truncate truncates file of <path> to given size by <size>.
 func Truncate(path string, size int) error {
     return os.Truncate(path, int64(size))
 }
 
-// (文本)写入文件内容
+// PutContents puts string <content> to file of <path>.
+// It creates file of <path> recursively if it does not exist.
 func PutContents(path string, content string) error {
     return putContents(path, []byte(content), os.O_WRONLY|os.O_CREATE|os.O_TRUNC, gDEFAULT_PERM)
 }
 
-// (文本)追加内容到文件末尾
+// PutContentsAppend appends string <content> to file of <path>.
+// It creates file of <path> recursively if it does not exist.
 func PutContentsAppend(path string, content string) error {
     return putContents(path, []byte(content), os.O_WRONLY|os.O_CREATE|os.O_APPEND, gDEFAULT_PERM)
 }
 
-// (二进制)写入文件内容
+// PutBinContents puts binary <content> to file of <path>.
+// It creates file of <path> recursively if it does not exist.
 func PutBinContents(path string, content []byte) error {
     return putContents(path, content, os.O_WRONLY|os.O_CREATE|os.O_TRUNC, gDEFAULT_PERM)
 }
 
-// (二进制)追加内容到文件末尾
+// PutBinContentsAppend appends binary <content> to file of <path>.
+// It creates file of <path> recursively if it does not exist.
 func PutBinContentsAppend(path string, content []byte) error {
     return putContents(path, content, os.O_WRONLY|os.O_CREATE|os.O_APPEND, gDEFAULT_PERM)
 }
 
-// 获得文件内容下一个指定字节的位置
+// GetNextCharOffset returns the file offset for given <char> starting from <start>.
 func GetNextCharOffset(reader io.ReaderAt, char byte, start int64) int64 {
     buffer := make([]byte, gREAD_BUFFER)
     offset := start
@@ -100,7 +104,8 @@ func GetNextCharOffset(reader io.ReaderAt, char byte, start int64) int64 {
     return -1
 }
 
-// 获得文件内容下一个指定字节的位置
+// GetNextCharOffsetByPath returns the file offset for given <char> starting from <start>.
+// It opens file of <path> for reading with os.O_RDONLY flag and default perm.
 func GetNextCharOffsetByPath(path string, char byte, start int64) int64 {
     if f, err := OpenWithFlagPerm(path, os.O_RDONLY, gDEFAULT_PERM); err == nil {
         defer f.Close()
@@ -109,7 +114,10 @@ func GetNextCharOffsetByPath(path string, char byte, start int64) int64 {
     return -1
 }
 
-// 获得文件内容直到下一个指定字节的位置(返回值包含该位置字符内容)
+// GetBinContentsTilChar returns the contents of the file as []byte 
+// until the next specified byte <char> position.
+//
+// Note: Returned value contains the character of the last position.
 func GetBinContentsTilChar(reader io.ReaderAt, char byte, start int64) ([]byte, int64) {
     if offset := GetNextCharOffset(reader, char, start); offset != -1 {
         return GetBinContentsByTwoOffsets(reader, start, offset + 1), offset
@@ -117,7 +125,11 @@ func GetBinContentsTilChar(reader io.ReaderAt, char byte, start int64) ([]byte,
     return nil, -1
 }
 
-// 获得文件内容直到下一个指定字节的位置(返回值包含该位置字符内容)
+// GetBinContentsTilCharByPath returns the contents of the file given by <path> as []byte 
+// until the next specified byte <char> position.
+// It opens file of <path> for reading with os.O_RDONLY flag and default perm.
+//
+// Note: Returned value contains the character of the last position.
 func GetBinContentsTilCharByPath(path string, char byte, start int64) ([]byte, int64) {
     if f, err := OpenWithFlagPerm(path, os.O_RDONLY, gDEFAULT_PERM); err == nil {
         defer f.Close()
@@ -126,7 +138,9 @@ func GetBinContentsTilCharByPath(path string, char byte, start int64) ([]byte, i
     return nil, -1
 }
 
-// 获得文件内容中两个offset之间的内容 [start, end)
+// GetBinContentsByTwoOffsets returns the binary content as []byte from <start> to <end>.
+// Note: Returned value does not contain the character of the last position, which means
+// it returns content range as [start, end).
 func GetBinContentsByTwoOffsets(reader io.ReaderAt, start int64, end int64) []byte {
     buffer := make([]byte, end - start)
     if _, err := reader.ReadAt(buffer, start); err != nil {
@@ -135,7 +149,10 @@ func GetBinContentsByTwoOffsets(reader io.ReaderAt, start int64, end int64) []by
     return buffer
 }
 
-// 获得文件内容中两个offset之间的内容 [start, end)
+// GetBinContentsByTwoOffsetsByPath returns the binary content as []byte from <start> to <end>.
+// Note: Returned value does not contain the character of the last position, which means
+// it returns content range as [start, end).
+// It opens file of <path> for reading with os.O_RDONLY flag and default perm.
 func GetBinContentsByTwoOffsetsByPath(path string, start int64, end int64) []byte {
     if f, err := OpenWithFlagPerm(path, os.O_RDONLY, gDEFAULT_PERM); err == nil {
         defer f.Close()

g/os/gfile/gfile_search.go

@@ -13,31 +13,25 @@ import (
     "github.com/gogf/gf/g/container/garray"
 )
 
-
-// 如果给定绝对路径将会去掉其中的相对路径符号后返回；
-// 如果是给定的相对路径，那么将会按照以下路径优先级搜索文件(重复路径会去重)：
-// prioritySearchPaths、当前工作目录、二进制文件目录、源码main包目录(开发环境下)
+// Search searches file by name <name> in following paths with priority:
+// prioritySearchPaths, Pwd()、SelfDir()、MainPkgPath().
+// It returns the absolute file path of <name> if found, or en empty string if not found.
 func Search(name string, prioritySearchPaths...string) (realPath string, err error) {
-    // 是否绝对路径
+    // Check if it's a absolute path.
     realPath = RealPath(name)
     if realPath != "" {
         return
     }
-    // 相对路径搜索
+    // Search paths array.
     array := garray.NewStringArray(true)
-    // 自定义优先路径
     array.Append(prioritySearchPaths...)
-    // 用户工作目录
-    array.Append(Pwd())
-    // 二进制所在目录
-    array.Append(SelfDir())
-    // 源码main包目录
+    array.Append(Pwd(), SelfDir())
     if path := MainPkgPath(); path != "" {
         array.Append(path)
     }
-    // 路径去重
+    // Remove repeated items.
     array.Unique()
-    // 执行相对路径搜索
+    // Do the searching.
     array.RLockFunc(func(array []string) {
         path := ""
         for _, v := range array {
@@ -48,7 +42,7 @@ func Search(name string, prioritySearchPaths...string) (realPath string, err err
             }
         }
     })
-    // 目录不存在错误处理
+    // If it fails searching, it returns formatted error.
     if realPath == "" {
         buffer := bytes.NewBuffer(nil)
         buffer.WriteString(fmt.Sprintf("cannot find file/folder \"%s\" in following paths:", name))

g/os/gfile/gfile_size.go

@@ -11,7 +11,7 @@ import (
     "os"
 )
 
-// 文件大小(bytes)
+// Size returns the size of file specified by <path> in byte.
 func Size(path string) int64 {
     s, e := os.Stat(path)
     if e != nil {
@@ -20,12 +20,12 @@ func Size(path string) int64 {
     return s.Size()
 }
 
-// 格式化文件大小
+// ReadableSize formats size of file given by <path>, for more human readable.
 func ReadableSize(path string) string {
     return FormatSize(float64(Size(path)))
 }
 
-// 格式化文件大小
+// FormatSize formats size <raw> for more human readable.
 func FormatSize(raw float64) string {
     var t float64 = 1024
     var d float64 = 1

g/os/gfile/gfile_time.go

@@ -10,7 +10,7 @@ import (
     "os"
 )
 
-// 文件修改时间(时间戳，秒)
+// MTime returns the modification time of file given by <path> in second.
 func MTime(path string) int64 {
     s, e := os.Stat(path)
     if e != nil {
@@ -19,7 +19,7 @@ func MTime(path string) int64 {
     return s.ModTime().Unix()
 }
 
-// 文件修改时间(时间戳，毫秒)
+// MTimeMillisecond returns the modification time of file given by <path> in millisecond.
 func MTimeMillisecond(path string) int64 {
     s, e := os.Stat(path)
     if e != nil {