provide go doc comments for exported types and functions

pkg/vcs/git.go

@@ -30,6 +30,8 @@ type gitVCS struct {
 	auth   Auth
 }
 
+// NewGit return a go-git VCS client implementation that provides information
+// about the specific module using the pgiven authentication mechanism.
 func NewGit(l logger, module string, auth Auth) VCS {
 	return &gitVCS{log: l, module: module, auth: auth}
 }

pkg/vcs/vcs.go

@@ -13,11 +13,15 @@ import (
 
 type logger = func(v ...interface{})
 
+// Version represents a semantic version of a module.
 type Version string
 
 var reSemVer = regexp.MustCompile(`^v\d+\.\d+\.\d+$`)
 
+// IsSemVer returns true if a version string is a semantic version e.g. vX.Y.Z.
 func (v Version) IsSemVer() bool { return reSemVer.MatchString(string(v)) }
+
+// Hash returns a commit hash if a version is of a form v0.0.0-timestamp-hash.
 func (v Version) Hash() string {
 	fields := strings.Split(string(v), "-")
 	if len(fields) != 3 {
@@ -26,26 +30,38 @@ func (v Version) Hash() string {
 	return fields[2]
 }
 
+// Module is a source code snapshot for which one can get the commit timestamp
+// or the actual ZIP with the source code in it.
 type Module interface {
 	Timestamp(ctx context.Context, version Version) (time.Time, error)
 	Zip(ctx context.Context, version Version) (io.ReadCloser, error)
 }
 
+// VCS is a version control system client. It can list available versions from
+// the remote, as well as fetch module data such as timestamp or zip snapshot.
 type VCS interface {
 	List(ctx context.Context) ([]Version, error)
 	Module
 }
 
+// Auth defines a typical VCS authentication mechanism, such as SSH key or
+// username/password.
 type Auth struct {
 	Username string
 	Password string
 	Key      string
 }
 
-func NoAuth() Auth                            { return Auth{} }
-func Password(username, password string) Auth { return Auth{Username: username, Password: password} }
-func Key(key string) Auth                     { return Auth{Key: key} }
+// NoAuth returns an Auth implementation that uses no authentication at all.
+func NoAuth() Auth { return Auth{} }
 
+// Password returns an Auth implementation that authenticate via username and password.
+func Password(username, password string) Auth { return Auth{Username: username, Password: password} }
+
+// Key returns an Auth implementation that uses key file authentication mechanism.
+func Key(key string) Auth { return Auth{Key: key} }
+
+// MetaImports resolved module import path for certain hosts using the special <meta> tag.
 func MetaImports(ctx context.Context, module string) (string, error) {
 	if strings.HasPrefix(module, "github.com/") || strings.HasPrefix(module, "bitbucket.org/") {
 		return module, nil