Improving code documentation by adding comments

Improving documentation

Signed-off-by: Jonas Franz <info@jonasfranz.de>

DOCS.md

@@ -4,7 +4,9 @@ You must provide in your configuration:
 
 * `project_identifier` - Identifier of your Crowdin project (also available as secret  `CROWDIN_IDENTIFIER`)
 * `project_key` - API Key of your Crowdin project (also available as secret  `CROWDIN_KEY`)
-* `files` - Map of files with the crowdin file name as key and the to-upload file-path as value.
+* `files` - Map of files to upload to Crowdin
+  * key: the Crowdin file name
+  * value: the real path the to file
 
 Information about API keys: https://support.crowdin.com/api/api-integration-setup/
 ## Example

plugin.go

@@ -13,23 +13,28 @@ import (
 )
 
 type (
+	// Files is a mapping between the crowdin path and the real file path
 	Files map[string]string
 
+	// Config stores the credentials for the crowdin API
 	Config struct {
 		Key        string
 		Identifier string
 	}
 
+	// Plugin represents the drone-crowdin plugin including config and file-mapping.
 	Plugin struct {
 		Config Config
 		Files  Files
 	}
 )
 
+// ToURL returns the API-endpoint including identifier and API-KEY
 func (c Config) ToURL() string {
 	return fmt.Sprintf("https://api.crowdin.com/api/project/%s/update-file?key=%s", c.Identifier, c.Key)
 }
 
+// Exec starts the plugin and updates the crowdin translation by uploading files from the files map
 func (p Plugin) Exec() error {
 	if len(p.Files) > 20 {
 		return fmt.Errorf("20 files max are allowed to upload. %d files given", len(p.Files))
@@ -37,7 +42,7 @@ func (p Plugin) Exec() error {
 
 	body := &bytes.Buffer{}
 	writer := multipart.NewWriter(body)
-	for crowdin_path, path := range p.Files {
+	for crowdinPath, path := range p.Files {
 		var err error
 		var file *os.File
 		if file, err = os.Open(path); err != nil {
@@ -45,7 +50,7 @@ func (p Plugin) Exec() error {
 		}
 		defer file.Close()
 
-		part, err := writer.CreateFormFile(fmt.Sprintf("files[%s]", crowdin_path), crowdin_path)
+		part, err := writer.CreateFormFile(fmt.Sprintf("files[%s]", crowdinPath), crowdinPath)
 		if err != nil {
 			return err
 		}
@@ -77,13 +82,13 @@ func (p Plugin) Exec() error {
 		return err
 	}
 	if resp.StatusCode != 200 {
-		var err_response = new(responses.Error)
+		var errResponse = new(responses.Error)
 		decoder := xml.NewDecoder(body)
 		decoder.CharsetReader = charset.NewReaderLabel
-		if err := decoder.Decode(&err_response); err != nil {
+		if err := decoder.Decode(&errResponse); err != nil {
 			return err
 		}
-		return err_response
+		return errResponse
 	} else {
 		var success = new(responses.Success)
 		decoder := xml.NewDecoder(body)

responses/responses.go

@@ -5,21 +5,25 @@ import (
 	"fmt"
 )
 
+// Error is a crowdin error message
 type Error struct {
 	XMLName xml.Name `xml:"error"`
 	Code    int      `xml:"code"`
 	Message string   `xml:"message"`
 }
 
+// Error implements the error interface to handle like an error
 func (e *Error) Error() string {
 	return fmt.Sprintf("Error from crowdin: %s (error code %d)", e.Message, e.Code)
 }
 
+// Success is a crowdin success message
 type Success struct {
 	XMLName xml.Name `xml:"success"`
 	Stats   []File   `xml:"stats>file"`
 }
 
+// File represents the status of an uploaded file
 type File struct {
 	XMLName xml.Name `xml:"file"`
 	Name    string   `xml:"name,attr"`

types.go

@@ -2,18 +2,22 @@ package main
 
 import "encoding/json"
 
+// StringMapFlag represents a string-based map as a cli flag
 type StringMapFlag struct {
 	parts map[string]string
 }
 
+// String is implemented from cli
 func (s *StringMapFlag) String() string {
 	return ""
 }
 
+// Get returns the parsed map
 func (s *StringMapFlag) Get() map[string]string {
 	return s.parts
 }
 
+// Set parses the map (via json)
 func (s *StringMapFlag) Set(value string) error {
 	s.parts = map[string]string{}
 	err := json.Unmarshal([]byte(value), &s.parts)