add documentation

pkg/gomod/gomod.go

@@ -7,26 +7,23 @@ import (
 	"golang.org/x/mod/modfile"
 )
 
-type logger interface {
-	Logf(f string, s ...interface{})
-	Debugf(f string, s ...interface{})
-}
-
+// GoMod represents a Go Modules parser.
+// Running LoadAndComputePairs with a filename will return a slice of parsed dependencies.
 type GoMod struct {
 	IncludeIndirect bool
 	ProxyLoader     Queryer
 	Logger          logger
 }
 
-func isReplaced(module string, replaces []*modfile.Replace) bool {
-	for i := range replaces {
-		if module == replaces[i].Old.Path {
-			return true
-		}
-	}
-	return false
+// logger is an extremely simple leveled logger
+type logger interface {
+	Logf(f string, s ...interface{})
+	Debugf(f string, s ...interface{})
 }
 
+// LoadAndComputePairs takes a filename of a go.mod file,
+// runs the resolution algorithm in the provided Querier,
+// and returns parsed pairs of dependencies and their latest versions.
 func (g *GoMod) LoadAndComputePairs(filename string) ([]libyear.Pair, error) {
 	b, err := os.ReadFile(filename)
 	if err != nil {
@@ -59,3 +56,12 @@ func (g *GoMod) LoadAndComputePairs(filename string) ([]libyear.Pair, error) {
 	}
 	return pairs, nil
 }
+
+func isReplaced(module string, replaces []*modfile.Replace) bool {
+	for i := range replaces {
+		if module == replaces[i].Old.Path {
+			return true
+		}
+	}
+	return false
+}

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/"