Add more doc in the code

Author: rm3l

pkg/branch/branch.go

@@ -11,6 +11,9 @@ const _replacementCharacter = "-"
 
 var _regexp = regexp.MustCompile("[^A-Za-z0-9.]+")
 
+// GenerateName generates a new branch name off of the identifier and title specified.
+// Both the identifier and title must not be blank.
+// Leading hyphens (prefix and suffix) are removed from the name returned.
 func GenerateName(id string, title string) (string, error) {
 	if id == "" || strings.TrimSpace(id) == "" {
 		return "", errors.New("id must not be blank")

pkg/branch/doc.go

@@ -0,0 +1,2 @@
+// Package branch allows to perform operations like generating a new branch name
+package branch

pkg/issue/doc.go

@@ -0,0 +1,2 @@
+// Package issue allows to query on issues against the remote issue provider
+package issue

pkg/issue/github.go

@@ -8,23 +8,33 @@ import (
 	"strconv"
 )
 
+// GHIssueFinder is a struct type that implements the issue.Finder interface
 type GHIssueFinder struct{}
 
+// This provides a compile-safe way of making sure GHIssueFinder implements the issue.Finder interface
+var _ Finder = GHIssueFinder{}
+
+// _GhIssueInfo is a struct used to unmarshal GitHub API responses.
+// It needs to be exported but is not intended to be used directly.
 type _GhIssueInfo struct {
-	Number int    `json:"number"`
-	Title  string `json:"title"`
+	// Number is the GitHub issue number
+	Number int `json:"number"`
+	// Title is the GitHub issue title
+	Title string `json:"title"`
 }
 
+// NewGHIssueFinder returns a new object of type GHIssueFinder
 func NewGHIssueFinder() *GHIssueFinder {
 	return &GHIssueFinder{}
 }
 
+// FindById allows to retrieve an issue given its identifier.
+// It optionally writes any relevant warnings or messages to eventually output into the io.Writer object specified.
 func (g GHIssueFinder) FindById(w io.Writer, repo string, id string) (Info, error) {
 	args := []string{"issue", "view", id, "--json", "number,title"}
 	if repo != "" {
 		args = append(args, "-R", repo)
 	}
-	var issueInfo _GhIssueInfo
 	stdOut, stdErr, err := gh.Exec(args...)
 	if err != nil {
 		return Info{}, err
@@ -33,6 +43,7 @@ func (g GHIssueFinder) FindById(w io.Writer, repo string, id string) (Info, erro
 		//goland:noinspection GoUnhandledErrorResult
 		fmt.Fprintln(w, stdErrStr)
 	}
+	var issueInfo _GhIssueInfo
 	err = json.Unmarshal(stdOut.Bytes(), &issueInfo)
 	return Info{
 		Id:    strconv.Itoa(issueInfo.Number),

pkg/issue/issue.go

@@ -2,11 +2,16 @@ package issue
 
 import "io"
 
+// Info is a generic struct representing a given issue
 type Info struct {
 	Id    string
 	Title string
 }
 
+// Finder is the interface used to manipulate issues
 type Finder interface {
-	FindById(w io.Writer, repo string, issue string) (Info, error)
+
+	// FindById allows to retrieve an issue given its identifier.
+	// It optionally writes any relevant warnings or messages to eventually output into the io.Writer object specified.
+	FindById(w io.Writer, repo string, id string) (Info, error)
 }