add documentation

pkg/gomod/modproxy.go

@@ -13,6 +13,7 @@ import (
 	"git.yetaga.in/alazyreader/libyear/pkg/libyear"
 )
 
+// A Queryer holds settings for a
 type Queryer struct {
 	Root   string
 	Client http.Client
@@ -25,11 +26,19 @@ type majorVersion struct {
 	version int
 }
 
+// GetLatestVersion returns the "latest" major version of a module,
+// jumping across MVS boundaries:
+// i.e. github.com/foo/bar => github.com/foo/bar/v2 in the case of one version bump
+// github.com/foo/baz/v2 => github.com/foo/baz/v6 in the case of a large jump
+// github.com/foo/quuz/v2 => github.com/foo/quuz/v2 in the case of no jump at all.
 func (q *Queryer) GetLatestVersion(module string) libyear.Info {
 	latestMod := q.findLatestMajorVersion(module)
 	return q.makeProxyRequest(latestMod + "/@latest")
 }
 
+// GetVersion returns the proxy's information about a given version of a module.
+// `module` in this case is a fully-disambiguated MVS name (github.com/foo/bar/v2),
+// and `version` is a version identifier as defined in `https://blog.golang.org/publishing-go-modules#TOC_3.`
 func (q *Queryer) GetVersion(module string, version string) libyear.Info {
 	if !strings.HasPrefix(version, "v") {
 		return libyear.Info{
@@ -44,9 +53,6 @@ func (q *Queryer) GetVersion(module string, version string) libyear.Info {
 }
 
 // given a module, return the "latest" major version of that module, fully defined
-// i.e. github.com/foo/bar => github.com/foo/bar/v2 in the case of one version bump
-// github.com/foo/baz/v2 => github.com/foo/baz/v6 in the case of a large jump
-// github.com/foo/quuz/v2 => github.com/foo/quuz/v2 in the case of no jump at all!
 func (q *Queryer) findLatestMajorVersion(module string) string {
 	for {
 		nextModule := incrementMajorVersion(module)
@@ -58,6 +64,7 @@ func (q *Queryer) findLatestMajorVersion(module string) string {
 	}
 }
 
+// handle calling the go module proxy
 func (q *Queryer) makeProxyRequest(mod string) libyear.Info {
 	if q.Root == "" {
 		q.Root = "https://proxy.golang.org/"