Merge pull request #219 from qiniu/develop

add comment to exported symbol

CHANGELOG.md

@@ -1,5 +1,6 @@
 # 2.3.6
 1. 修复m3u8replace 上传的问题
+2. 加入reportCard检测代码质量
 
 # 2.3.5
 1. 增加token命令，创建Qbox token, qiniuToken, uploadToken

cmd/account.go

@@ -28,6 +28,7 @@ var cmdAccount = &cobra.Command{
 	Run: Account,
 }
 
+// 【account】获取本地保存的用户的AK/AK/Name信息； 设置保存用户AK/SK信息到本地
 func Account(cmd *cobra.Command, params []string) {
 	if len(params) == 0 {
 		account, gErr := iqshell.GetAccount()

cmd/alilistbucket.go

@@ -17,6 +17,7 @@ func init() {
 	RootCmd.AddCommand(aliCmd)
 }
 
+// 【alilistbucket】列举阿里空间中的文件列表
 func AliListBucket(cmd *cobra.Command, params []string) {
 	dataCenter := params[0]
 	bucket := params[1]

cmd/bucket.go

@@ -31,6 +31,7 @@ func init() {
 	RootCmd.AddCommand(bucketsCmd, domainsCmd)
 }
 
+// 【buckets】获取一个用户的所有的存储空间
 func GetBuckets(cmd *cobra.Command, params []string) {
 
 	bm := iqshell.GetBucketManager()
@@ -49,6 +50,7 @@ func GetBuckets(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【domains】获取一个空间绑定的CDN域名
 func GetDomainsOfBucket(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	bm := iqshell.GetBucketManager()

cmd/cdn.go

@@ -12,9 +12,14 @@ import (
 )
 
 const (
+	// CDN刷新一次性最大的刷新文件列表
 	BATCH_CDN_REFRESH_URLS_ALLOW_MAX = 100
+
+	// CDN目录刷新一次性最大的刷新目录数
 	BATCH_CDN_REFRESH_DIRS_ALLOW_MAX = 10
-	BATCH_CDN_PREFETCH_ALLOW_MAX     = 100
+
+	// 预取一次最大的预取数目
+	BATCH_CDN_PREFETCH_ALLOW_MAX = 100
 )
 
 var (
@@ -46,7 +51,7 @@ func init() {
 	RootCmd.AddCommand(cdnPreCmd, cdnRefreshCmd)
 }
 
-// 刷新CDN
+// 【cdnrefresh】刷新所有CDN节点
 func CdnRefresh(cmd *cobra.Command, params []string) {
 	var urlListFile string
 
@@ -123,7 +128,7 @@ func cdnRefresh(cm *cdn.CdnManager, urls []string, dirs []string) {
 	}
 }
 
-//  CDN 文件预取
+//  【cdnprefetch】CDN 文件预取
 func CdnPrefetch(cmd *cobra.Command, params []string) {
 	var urlListFile string
 

cmd/fop.go

@@ -30,6 +30,7 @@ func init() {
 	RootCmd.AddCommand(prefopCmd, fopCmd)
 }
 
+// 【prefop】根据persistentId查询异步处理的进度, 处理结果
 func Prefop(cmd *cobra.Command, params []string) {
 	persistentId := params[0]
 
@@ -42,6 +43,7 @@ func Prefop(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【pfop】 提交异步处理请求
 func Fop(cmd *cobra.Command, params []string) {
 	bucket, key, fops := params[0], params[1], params[2]
 

cmd/ip.go

@@ -10,9 +10,11 @@ import (
 )
 
 const (
+	// IP信息查询接口地址
 	TAOBAO_IP_QUERY = "http://ip.taobao.com/service/getIpInfo.php"
 )
 
+// 接口返回的IP信息
 type IpInfo struct {
 	Code int    `json:"code"`
 	Data IpData `json:"data"`
@@ -22,6 +24,7 @@ func (this IpInfo) String() string {
 	return fmt.Sprintf("%s", this.Data)
 }
 
+// ip 具体的信息
 type IpData struct {
 	Country   string `json:"country"`
 	CountryId string `json:"country_id"`
@@ -54,6 +57,7 @@ func init() {
 	RootCmd.AddCommand(ipQueryCmd)
 }
 
+// 【ip】查询ip的相关信息
 func IpQuery(cmd *cobra.Command, params []string) {
 	for _, ip := range params {
 		url := fmt.Sprintf("%s?ip=%s", TAOBAO_IP_QUERY, ip)

cmd/putfile.go

@@ -62,13 +62,15 @@ func init() {
 	RootCmd.AddCommand(formPutCmd, RePutCmd)
 }
 
+// 上传接口返回的文件信息
 type PutRet struct {
 	Key      string `json:"key"`
 	Hash     string `json:"hash"`
 	MimeType string `json:"mimeType"`
 	Fsize    int64  `json:"fsize"`
 }
 
+// 【fput】使用表单上传本地文件到七牛存储空间
 func FormPut(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -183,6 +185,8 @@ func FormPut(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 使用分片上传本地文件到七牛存储空间, 一般用于较大文件的上传
+// 文件会被分割成4M大小的块， 一块一块地上传文件
 func ResumablePut(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]

cmd/qdownload.go

@@ -12,7 +12,7 @@ import (
 )
 
 var qDownloadCmd = &cobra.Command{
-	Use:   "qdownload [<ThreadCount>] <LocalDownloadConfig>",
+	Use:   "qdownload [-c <ThreadCount>] <LocalDownloadConfig>",
 	Short: "Batch download files from the qiniu bucket",
 	Long:  "By default qdownload use 5 goroutines to download, it can be customized use -c <count> flag",
 	Args:  cobra.ExactArgs(1),
@@ -29,6 +29,9 @@ func init() {
 	RootCmd.AddCommand(qDownloadCmd)
 }
 
+// 【qdownload】下载七牛存储空间中的文件
+// 可以根据文件前缀下载符合要求的所有文件，也可以用户给到要下载的文件名字列表下载文件
+// 根据文件列表下载文件功能在文档中还没有公开，遇到有这个需求的客户比较少
 func QiniuDownload(cmd *cobra.Command, params []string) {
 
 	var downloadConfig iqshell.DownloadConfig

cmd/qupload.go

@@ -66,7 +66,8 @@ func parseUploadConfigFile(uploadConfigFile string, uploadConfig *iqshell.Upload
 	return
 }
 
-// upload cmd
+// [qupload]命令， 上传本地文件到七牛存储中
+// 该命令会读取配置文件， 上传本地文件系统的文件到七牛存储中; 可以设置多线程上传，默认的线程区间在[iqshell.MIN_UPLOAD_THREAD_COUNT, iqshell.MAX_UPLOAD_THREAD_COUNT]
 func QiniuUpload(cmd *cobra.Command, params []string) {
 
 	configFile := params[0]

cmd/qupload2.go

@@ -56,6 +56,7 @@ func init() {
 	RootCmd.AddCommand(qUpload2Cmd)
 }
 
+// 【qupload2】和命令【qupload】的功能一样，只是使用的是命令选项的方式提供配置信息
 func QiniuUpload2(cmd *cobra.Command, params []string) {
 
 	//check params

cmd/root.go

@@ -9,15 +9,17 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 	"os"
-	"os/user"
 	"path/filepath"
 	"runtime"
 	"strings"
 )
 
 var (
-	DebugFlag   bool // debug flag
-	VersionFlag bool // version flag
+	// 开启命令行的调试模式
+	DebugFlag bool
+
+	// qshell 版本信息， qshell -v
+	VersionFlag bool
 	cfgFile     string
 	local       bool
 )
@@ -53,7 +55,7 @@ __custom_func() {
 `
 )
 
-// cobra root cmd
+// cobra root cmd, all other commands is children or subchildren of this root cmd
 var RootCmd = &cobra.Command{
 	Use:                    "qshell",
 	Short:                  "Qiniu commandline tool for managing your bucket and CDN",
@@ -96,12 +98,12 @@ func initConfig() {
 		}
 		viper.SetConfigFile(jsonConfigFile)
 	} else {
-		curUser, gErr := user.Current()
-		if gErr != nil {
-			fmt.Fprintf(os.Stderr, "get current user: %v\n", gErr)
+		homeDir, hErr := homedir.Dir()
+		if hErr != nil {
+			fmt.Fprintf(os.Stderr, "get current home directory: %v\n", hErr)
 			os.Exit(1)
 		}
-		viper.AddConfigPath(curUser.HomeDir)
+		viper.AddConfigPath(homeDir)
 		viper.SetConfigName(".qshell")
 	}
 

cmd/rs.go

@@ -164,6 +164,7 @@ func init() {
 		saveAsCmd, m3u8DelCmd, m3u8RepCmd, privateUrlCmd, lsBucketCmd2)
 }
 
+// 【dircache】扫描本地文件目录， 形成一个关于文件信息的文本文件
 func DirCache(cmd *cobra.Command, params []string) {
 	var cacheResultFile string
 	cacheRootPath := params[0]
@@ -178,6 +179,7 @@ func DirCache(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【listbucket2】 使用v2接口列举存储空间中的文件
 func ListBucket2(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 
@@ -226,6 +228,7 @@ func ListBucket2(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【listbucket】列举七牛存储空间中的文件列表
 func ListBucket(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 
@@ -236,6 +239,7 @@ func ListBucket(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【get】下载七牛存储中的一个文件， 该命令不需要存储空间绑定有可访问的CDN域名
 func Get(cmd *cobra.Command, params []string) {
 
 	bucket := params[0]
@@ -254,6 +258,7 @@ func Get(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【stat】获取文件的meta信息，包括文件名字，hash， 上传时间，文件大小等信息
 func Stat(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -268,6 +273,7 @@ func Stat(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【delete】删除七牛存储空间中的文件
 func Delete(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -280,6 +286,7 @@ func Delete(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【move】 移动一个七牛存储空间的文件到另一个七牛的存储空间，该命令只适用于同属一个存储区域的存储空间中的文件
 func Move(cmd *cobra.Command, params []string) {
 	srcBucket := params[0]
 	srcKey := params[1]
@@ -297,6 +304,7 @@ func Move(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【copy】拷贝一个七牛存储空间的文件到另一个七牛的存储空间，该命令只适用于同属一个存储区域的存储空间中的文件
 func Copy(cmd *cobra.Command, params []string) {
 	srcBucket := params[0]
 	srcKey := params[1]
@@ -313,6 +321,7 @@ func Copy(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【chtype】改变七牛存储空间的文件的MimeType
 func Chgm(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -326,6 +335,7 @@ func Chgm(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【chtype】改变文件的存储类型，在七牛中存储的文件分为标准存储和低频存储
 func Chtype(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -345,6 +355,7 @@ func Chtype(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【expire】给存储在七牛空间中的文件设置删除属性，设置以后，到指定时间会自动删除该文件
 func DeleteAfterDays(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -364,6 +375,7 @@ func DeleteAfterDays(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【fetch】通过http链接抓取网上的资源到七牛存储空间
 func Fetch(cmd *cobra.Command, params []string) {
 	remoteResUrl := params[0]
 	bucket := params[1]
@@ -390,6 +402,7 @@ func Fetch(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【cdnprefetch】CDN文件预取, 预取文件到CDN节点和父层节点
 func Prefetch(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	key := params[1]
@@ -402,6 +415,7 @@ func Prefetch(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【saveas】打印输出主动saveas链接
 func Saveas(cmd *cobra.Command, params []string) {
 	publicUrl := params[0]
 	saveBucket := params[1]
@@ -417,6 +431,7 @@ func Saveas(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【m3u8delete】删除m3u8文件，包括m3u8文件本身和分片文件
 func M3u8Delete(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	m3u8Key := params[1]
@@ -452,6 +467,7 @@ func M3u8Delete(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【m3u8replace】替换m3u8文件中的域名信息
 func M3u8Replace(cmd *cobra.Command, params []string) {
 	bucket := params[0]
 	m3u8Key := params[1]
@@ -468,6 +484,7 @@ func M3u8Replace(cmd *cobra.Command, params []string) {
 	}
 }
 
+// 【privateurl】打印七牛私有空间的文件的下载链接(私有空间的文件下载去要鉴权验证)
 func PrivateUrl(cmd *cobra.Command, params []string) {
 	publicUrl := params[0]
 	var deadline int64