Refactor usages

README.md

@@ -5,65 +5,25 @@
 [![API Reference](http://img.shields.io/badge/api-reference-green.svg)](http://docs.qingcloud.com/qingstor/)
 [![License](http://img.shields.io/badge/license-apache%20v2-blue.svg)](https://github.com/yunify/qingstor-sdk-go/blob/master/LICENSE)
 
-The official QingStor SDK for the Go programming language.
-
-## Getting Started
-
-### Installation
-
-Refer to the [Installation Guide](docs/installation.md), and have this SDK installed.
-
-### Preparation
-
-Before your start, please go to [QingCloud Console](https://console.qingcloud.com/access_keys/) to create a pair of QingCloud API AccessKey.
-
-___API AccessKey Example:___
-
-``` yaml
-access_key_id: 'ACCESS_KEY_ID_EXAMPLE'
-secret_access_key: 'SECRET_ACCESS_KEY_EXAMPLE'
-```
+English | [中文](README_zh-CN.md)
 
-### Usage
-
-Now you are ready to code. You can read the detailed guides in the list below to have a clear understanding or just take the quick start code example.
-
-Checkout our [releases](https://github.com/yunify/qingstor-sdk-go/releases) and [change log](https://github.com/yunify/qingstor-sdk-go/blob/master/CHANGELOG.md) for information about the latest features, bug fixes and new ideas.
-
-- [Configuration Guide](docs/configuration.md)
-- [QingStor Service Usage Guide](docs/qingstor_service_usage.md)
-
-___Quick Start Code Example:___
-
-``` go
-package main
-
-import (
-	"fmt"
-
-	"github.com/yunify/qingstor-sdk-go/v3/config"
-	qs "github.com/yunify/qingstor-sdk-go/v3/service"
-)
+The official QingStor SDK for the Go programming language.
 
-func main() {
-	conf, _ := config.New("ACCESS_KEY_ID", "SECRET_ACCESS_KEY")
+Before you start using the SDK, make sure you have a basic understanding of the concepts of [QingStor object storage](https://docs.qingcloud.com/qingstor/api/common/overview.html) (such as Zone, Service, Bucket, Object, etc.).
 
-	// Initialize service object for QingStor.
-	qsService, _ := qs.Init(conf)
+This SDK try to keep a one-to-one correspondence with the methods on the [QingCloud QingStor object storage documentation](https://docs.qingcloud.com/qingstor/api/). For details of each method, please refer to the corresponding chapter in the link.
 
-	// List all buckets.
-	qsOutput, _ := qsService.ListBuckets(&qs.ListBucketsInput{})
+## Quick Start
 
-	// Print HTTP status code.
-	fmt.Println(qs.IntValue(qsOutput.StatusCode))
+Now you are ready to code. You can read the detailed guides in the list below to have a clear understanding.
 
-	// Print the count of buckets.
-	fmt.Println(qs.IntValue(qsOutput.Count))
+- [Preparation](./docs/prepare.md)
+- [Installation](./docs/install.md)
+- [Configuration](./docs/config.md)
+- [Service Initialization](./docs/service.md)
+- [Code Examples](./docs/examples.md)
 
-	// Print the first bucket name.
-	fmt.Println(qs.StringValue(qsOutput.Buckets[0].Name))
-}
-```
+Checkout our [releases](https://github.com/yunify/qingstor-sdk-go/releases) and [change log](./CHANGELOG.md) for information about the latest features, bug fixes and new ideas.
 
 ## Reference Documentations
 

README_zh-CN.md

@@ -0,0 +1,44 @@
+# QingStor SDK for Go
+
+[![Build Status](https://travis-ci.org/yunify/qingstor-sdk-go.svg?branch=master)](https://travis-ci.org/yunify/qingstor-sdk-go)
+[![Go Report Card](https://goreportcard.com/badge/github.com/yunify/qingstor-sdk-go)](https://goreportcard.com/report/github.com/yunify/qingstor-sdk-go)
+[![API Reference](http://img.shields.io/badge/api-reference-green.svg)](http://docs.qingcloud.com/qingstor/)
+[![License](http://img.shields.io/badge/license-apache%20v2-blue.svg)](https://github.com/yunify/qingstor-sdk-go/blob/master/LICENSE)
+
+[English](README.md) | 中文
+
+Go 语言版本的 QingStor 官方 SDK.
+
+在开始使用 SDK 之前，请确保你对[青云 QingStor 对象存储基本概念](https://docs.qingcloud.com/qingstor/api/common/overview.html)（如 Zone，Service，Bucket，Object 等）有一定的了解。
+
+本 SDK 与[青云 QingStor 对象存储帮助文档](https://docs.qingcloud.com/qingstor/api/)上的方法尽量保持一一对应，具体每个方法的详细说明请查看上述链接中的对应章节。
+
+## 快速开始
+
+你可以根据自己的需要针对性地阅读列表中的内容。
+
+- [准备工作](./docs/prepare_zh-CN.md)
+- [安装](./docs/install_zh-CN.md)
+- [配置](./docs/config_zh-CN.md)
+- [初始化服务](./docs/service_zh-CN.md)
+- [代码示例](./docs/examples_zh-CN.md)
+
+查看我们的 [发布历史](https://github.com/yunify/qingstor-sdk-go/releases) 和 [更改日志](./CHANGELOG.md) 获取最新的特性和 bug 修复。
+
+## 参考文档
+
+- [QingStor 文档](https://docs.qingcloud.com/qingstor/index.html)
+- [QingStor 指南](https://docs.qingcloud.com/qingstor/guide/index.html)
+- [QingStor APIs](https://docs.qingcloud.com/qingstor/api/index.html)
+
+## 贡献
+
+1. Fork 仓库 ( https://github.com/yunify/qingstor-sdk-go/fork )
+2. 创建您的 feature 分支 (`git checkout -b new-feature`)
+3. 提交您的修改 (`git commit -asm 'Add some feature'`)
+4. 推送到您的 origin 仓库 (`git push origin new-feature`)
+5. 创建并提交相应的 Pull Request
+
+## 许可证
+
+The Apache License (Version 2.0, January 2004).

docs/configuration.md → docs/config.md

@@ -1,6 +1,6 @@
 # Configuration Guide
 
-## Summary
+## Overview
 
 This SDK uses a structure called "Config" to store and manage configuration, read comments of public functions in ["config/config.go"](https://github.com/yunify/qingstor-sdk-go/blob/master/config/config.go) for details.
 
@@ -21,24 +21,23 @@ connection_retries: 3
 
 # Valid log levels are "debug", "info", "warn", "error", and "fatal".
 log_level: 'warn'
-
 ```
 
 ## Usage
 
 Just create a config structure instance with your API Access Key, and initialize services you need with Init() function of the target service.
 
-### Code Snippet
+## Code Snippet
 
 Create default configuration
 
-``` go
+```go
 defaultConfig, _ := config.NewDefault()
 ```
 
 Create configuration from Access Key
 
-``` go
+```go
 configuration, _ := config.New("ACCESS_KEY_ID", "SECRET_ACCESS_KEY")
 
 anotherConfiguration := config.NewDefault()
@@ -48,19 +47,19 @@ anotherConfiguration.SecretAccessKey = "SECRET_ACCESS_KEY"
 
 Load user configuration
 
-``` go
+```go
 userConfig, _ := config.NewDefault().LoadUserConfig()
 ```
 
 Load configuration from config file
 
-``` go
+```go
 configFromFile, _ := config.NewDefault().LoadConfigFromFilepath("PATH/TO/FILE")
 ```
 
 Change API endpoint
 
-``` go
+```go
 moreConfiguration, _ := config.NewDefault()
 
 moreConfiguration.Protocol = "http"
@@ -70,7 +69,7 @@ moreConfiguration.Port = 80
 
 Change http timeout
 
-``` go
+```go
 customConfiguration, _ := config.NewDefault().LoadUserConfig()
 // For the default value refers to DefaultHTTPClientSettings in config package
 // ReadTimeout affect each call to HTTPResponse.Body.Read()

docs/config_zh-CN.md

@@ -0,0 +1,81 @@
+# 配置指南
+
+## 总览
+
+SDK 封装一个 `Config` struct 用于存储和管理配置信息，您可以通过 ["config/config.go"](https://github.com/yunify/qingstor-sdk-go/blob/master/config/config.go) 来获取它的详细信息（如内部成员和导出方法等）。
+
+除 `ACCESS_KEY_ID` 和 `SECRET_ACCESS_KEY` 之外，您还可以配置 `API服务器` 以进行私有云使用场景。 所有可用的可配置项目都列在默认配置文件中。
+
+___默认的 Config 对应的 yaml 文件:___
+
+``` yaml
+# QingStor services configuration
+
+access_key_id: 'ACCESS_KEY_ID'
+secret_access_key: 'SECRET_ACCESS_KEY'
+
+host: 'qingstor.com'
+port: 443
+protocol: 'https'
+connection_retries: 3
+
+# Valid log levels are "debug", "info", "warn", "error", and "fatal".
+log_level: 'warn'
+```
+
+## 使用
+
+只需使用 API Access Key Pair 来创建 `Config` 结构实例，并使用 service 包下的Init() 函数来初始化 Config 对应的服务。
+
+## 代码片段
+
+创建默认的 Config 结构。
+
+```go
+defaultConfig, _ := config.NewDefault()
+```
+
+通过密钥来创建 Config。
+
+```go
+configuration, _ := config.New("ACCESS_KEY_ID", "SECRET_ACCESS_KEY")
+
+anotherConfiguration := config.NewDefault()
+anotherConfiguration.AccessKeyID = "ACCESS_KEY_ID"
+anotherConfiguration.SecretAccessKey = "SECRET_ACCESS_KEY"
+```
+
+下面的代码从默认路径 `~/.qingstor/config.yaml` 读取配置信息来创建 Config。
+
+```go
+userConfig, _ := config.NewDefault().LoadUserConfig()
+```
+
+您也可以指定文件路径来初始化 Config。
+
+```go
+configFromFile, _ := config.NewDefault().LoadConfigFromFilepath("PATH/TO/FILE")
+```
+
+选择更换 API 服务器：
+
+```go
+moreConfiguration, _ := config.NewDefault()
+
+moreConfiguration.Protocol = "http"
+moreConfiguration.Host = "api.private.com"
+moreConfiguration.Port = 80
+```
+
+动态修改 http 超时时间：
+
+```go
+customConfiguration, _ := config.NewDefault().LoadUserConfig()
+// For the default value refers to DefaultHTTPClientSettings in config package
+// ReadTimeout affect each call to HTTPResponse.Body.Read()
+customConfiguration.HTTPSettings.ReadTimeout = 2 * time.Minute
+// WriteTimeout affect each write in io.Copy while sending HTTPRequest
+customConfiguration.HTTPSettings.WriteTimeout = 2 * time.Minute
+// Re-initialize the client to take effect
+customConfiguration.InitHTTPClient()
+```

docs/example/create_bucket.md

@@ -0,0 +1,36 @@
+# Create a Bucket
+
+## Code Snippet
+
+Initialize the Qingstor object with your AccessKeyID and SecretAccessKey.
+
+```go
+import (
+	"github.com/yunify/qingstor-sdk-go/v3/config"
+	"github.com/yunify/qingstor-sdk-go/v3/service"
+)
+
+var conf, _ = config.New("YOUR-ACCESS-KEY-ID", "YOUR--SECRET-ACCESS-KEY")
+var qingStor, _ = service.Init(conf)
+```
+
+Initialize a Bucket object according to the bucket name you set for subsequent creation:
+
+```go
+bucketName := "your-bucket-name"
+zoneName := "pek3b"
+bucketService, _ := qingStor.Bucket(bucketName, zoneName)
+```
+
+The `bucketService` object is used to manipulate the Bucket and can use all Bucket and Object level APIs. Now perform the real creation of the Bucket operation:
+
+```go
+if _, err := bucketService.Put(); err == nil {
+    fmt.Printf("Your bucket named \"%s\" in zone \"%s\" has been created successfully\n", bucketName, zoneName)
+} else {
+    fmt.Printf("Bucket creation failed with given message: %s\n", err)
+}
+```
+
+`bucketService.Put()` will create a Bucket in the specified zone.
+

docs/example/create_bucket_zh-CN.md

@@ -0,0 +1,36 @@
+# 创建一个 Bucket
+
+## 代码片段
+
+使用您的 AccessKeyID 和 SecretAccessKey 初始化 Qingstor 对象。
+
+```go
+import (
+	"github.com/yunify/qingstor-sdk-go/v3/config"
+	"github.com/yunify/qingstor-sdk-go/v3/service"
+)
+
+var conf, _ = config.New("YOUR-ACCESS-KEY-ID", "YOUR--SECRET-ACCESS-KEY")
+var qingStor, _ = service.Init(conf)
+```
+
+按照您设定的 bucket 名称初始化一个 Bucket 对象，以进行后续创建操作：
+
+```go
+bucketName := "your-bucket-name"
+zoneName := "pek3b"
+bucketService, _ := qingStor.Bucket(bucketName, zoneName)
+```
+
+`bucketService` 对象用于操作 Bucket，可以使用所有 Bucket 和 Object 级别的 API。现在执行真正的创建 Bucket 操作：
+
+```go
+if _, err := bucketService.Put(); err == nil {
+    fmt.Printf("Your bucket named \"%s\" in zone \"%s\" has been created successfully\n", bucketName, zoneName)
+} else {
+    fmt.Printf("Bucket creation failed with given message: %s\n", err)
+}
+```
+
+`bucketService.Put()` 会在指定 zone 创建 Bucket。 
+

docs/example/delete_bucket.md

@@ -0,0 +1,41 @@
+# Delete a Bucket
+
+## Code Snippet
+
+Initialize the Qingstor object with your AccessKeyID and SecretAccessKey.
+
+```go
+import (
+	"github.com/yunify/qingstor-sdk-go/v3/config"
+	"github.com/yunify/qingstor-sdk-go/v3/service"
+)
+
+var conf, _ = config.New("YOUR-ACCESS-KEY-ID", "YOUR--SECRET-ACCESS-KEY")
+var qingStor, _ = service.Init(conf)
+```
+
+Initialize a Bucket object according to the bucket name you set for subsequent creation:
+
+```go
+bucketName := "your-bucket-name"
+zoneName := "pek3b"
+bucketService, _ := qingStor.Bucket(bucketName, zoneName)
+```
+
+After created the object, we need perform the action to delete a Bucket：
+
+```go
+	if resp, err := bucketService.Delete(); err != nil {
+		fmt.Printf("Delete bucket(name: %s) failed with given error: %s\n", bucketName, err)
+	} else {
+		fmt.Printf("The status code expected: 204(actually: %d)\n", *resp.StatusCode)
+	}
+```
+
+The function that appears in the code above:
+- `bucketService.Delete()` Deletes a Bucket named `your-bucket-name` in the `pek3b` field.
+
+The object that appears in the above code:
+- The `resp` object is the return value of the `bucketService.Delete()` method.
+- `resp.StatusCode` stores the http status code for the api operation.
+