cmd/go/internal/{module,mvs}: document exported fields and methods
I needed some details about these identifiers in order to understand
https://golang.org/cl/114735, so I'm documenting what I learned for
future reference.
Please feel free to suggest improvements and/or corrections.
Change-Id: Idf2462fe1ad6c435c8abbb2e69fbfafaca66fcb8
Reviewed-on: https://go-review.googlesource.com/116235
Reviewed-by: Russ Cox <rsc@golang.org>
diff --git a/vendor/cmd/go/internal/module/module.go b/vendor/cmd/go/internal/module/module.go
index 1e8f74c..db40645 100644
--- a/vendor/cmd/go/internal/module/module.go
+++ b/vendor/cmd/go/internal/module/module.go
@@ -17,7 +17,14 @@
// A Version is defined by a module path and version pair.
type Version struct {
- Path string
+ Path string
+
+ // Version is usually a semantic version in canonical form.
+ // There are two exceptions to this general rule.
+ // First, the top-level target of a build has no specific version
+ // and uses Version = "".
+ // Second, during MVS calculations the version "none" is used
+ // to represent the decision to take no version of a given module.
Version string
}
diff --git a/vendor/cmd/go/internal/mvs/mvs.go b/vendor/cmd/go/internal/mvs/mvs.go
index 9e7816d..dccea00 100644
--- a/vendor/cmd/go/internal/mvs/mvs.go
+++ b/vendor/cmd/go/internal/mvs/mvs.go
@@ -281,6 +281,10 @@
// Downgrade returns a build list for the target module
// in which the given additional modules are downgraded.
+//
+// The versions to be downgraded may be unreachable from reqs.Latest and
+// reqs.Previous, but the methods of reqs must otherwise handle such versions
+// correctly.
func Downgrade(target module.Version, reqs Reqs, downgrade ...module.Version) ([]module.Version, error) {
list, err := reqs.Required(target)
if err != nil {
diff --git a/vendor/cmd/go/internal/vgo/load.go b/vendor/cmd/go/internal/vgo/load.go
index 67f878a..4ef52a1 100644
--- a/vendor/cmd/go/internal/vgo/load.go
+++ b/vendor/cmd/go/internal/vgo/load.go
@@ -397,6 +397,8 @@
modFile.AddRequire(root, info.Version)
}
+// mvsReqs implements mvs.Reqs for vgo's semantic versions, with any exclusions
+// or replacements applied internally.
type mvsReqs struct {
extra []module.Version
cache par.Cache
@@ -532,6 +534,8 @@
return v1
}
+// Latest returns the latest tagged version of the module at path,
+// or the latest untagged version if no version is tagged.
func (*mvsReqs) Latest(path string) (module.Version, error) {
// Note that query "latest" is not the same as
// using repo.Latest.
@@ -557,6 +561,8 @@
return repo.Versions("")
}
+// Previous returns the tagged version of m.Path immediately prior to
+// m.Version, or version "none" if no prior version is tagged.
func (*mvsReqs) Previous(m module.Version) (module.Version, error) {
list, err := versions(m.Path)
if err != nil {
