Merge pull request #1619 from jmank88/gps_doc

gps: improve documentation; add package doc
golang · Feb 8, 2018 · 93bcb36 · 93bcb36
2 parents 70b4da7 + 892b680
commit 93bcb36
Show file tree

Hide file tree

Showing 6 changed files with 19 additions and 21 deletions.
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -202,7 +202,7 @@ So, given a slice of the following versions:
 - Non-semver tags: `footag`
 - Revision: `f6e74e8d`
 
-Sorting for upgrade will result in the following slice.
+Sorting for upgrade will result in the following slice:
 
 `[v1.1.0 v1.0.0 v1.1.0-alpha1 master devel footag f6e74e8d]`
 

diff --git a/gps/bridge.go b/gps/bridge.go
@@ -16,8 +16,7 @@ import (
 // sourceBridge is an adapter to SourceManagers that tailor operations for a
 // single solve run.
 type sourceBridge interface {
-	// sourceBridge includes all the methods in the SourceManager interface except
-	// for Release().
+	// sourceBridge includes many methods from the SourceManager interface.
 	SourceExists(ProjectIdentifier) (bool, error)
 	SyncSourceFor(ProjectIdentifier) error
 	RevisionPresentIn(ProjectIdentifier, Revision) (bool, error)
@@ -26,14 +25,7 @@ type sourceBridge interface {
 	ExportProject(ProjectIdentifier, Version, string) error
 	DeduceProjectRoot(ip string) (ProjectRoot, error)
 
-	//sourceExists(ProjectIdentifier) (bool, error)
-	//syncSourceFor(ProjectIdentifier) error
 	listVersions(ProjectIdentifier) ([]Version, error)
-	//revisionPresentIn(ProjectIdentifier, Revision) (bool, error)
-	//listPackages(ProjectIdentifier, Version) (pkgtree.PackageTree, error)
-	//getManifestAndLock(ProjectIdentifier, Version, ProjectAnalyzer) (Manifest, Lock, error)
-	//exportProject(ProjectIdentifier, Version, string) error
-	//deduceProjectRoot(ip string) (ProjectRoot, error)
 	verifyRootDir(path string) error
 	vendorCodeExists(ProjectIdentifier) (bool, error)
 	breakLock()

diff --git a/gps/doc.go b/gps/doc.go
@@ -0,0 +1,6 @@
+// Copyright 2018 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package gps is a Go packaging solver library.
+package gps
diff --git a/gps/lock.go b/gps/lock.go
@@ -26,8 +26,8 @@ type Lock interface {
 }
 
 // LocksAreEq checks if two locks are equivalent. This checks that
-// all contained LockedProjects are equal, and optionally (if the third
-// parameter is true) whether the locks' input hashes are equal.
+// all contained LockedProjects are equal, and optionally (if `checkHash` is
+// true) whether the locks' input hashes are equal.
 func LocksAreEq(l1, l2 Lock, checkHash bool) bool {
 	// Cheapest ops first
 	if checkHash && !bytes.Equal(l1.InputsDigest(), l2.InputsDigest()) {

diff --git a/gps/lockdiff.go b/gps/lockdiff.go
@@ -167,7 +167,7 @@ func buildLockedProjectDiff(lp LockedProject) LockedProjectDiff {
 }
 
 // DiffProjects compares two projects and identifies the differences between them.
-// Returns nil if there are no differences
+// Returns nil if there are no differences.
 func DiffProjects(lp1 LockedProject, lp2 LockedProject) *LockedProjectDiff {
 	diff := LockedProjectDiff{Name: lp1.pi.ProjectRoot}
 

diff --git a/gps/version.go b/gps/version.go
@@ -16,7 +16,7 @@ import (
 // semantics beyond that which is literally embedded on the Go type.
 type VersionType uint8
 
-// VersionTypes for the four major classes of version we deal with
+// VersionTypes for the four major classes of version.
 const (
 	IsRevision VersionType = iota
 	IsVersion
@@ -39,7 +39,7 @@ const (
 type Version interface {
 	Constraint
 
-	// Indicates the type of version - Revision, Branch, Version, or Semver
+	// Indicates the type of version - Revision, Branch, Version, or Semver.
 	Type() VersionType
 }
 
@@ -53,11 +53,11 @@ type PairedVersion interface {
 
 	// Unpair returns the surface-level UnpairedVersion that half of the pair.
 	//
-	// It does NOT modify the original PairedVersion
+	// It does NOT modify the original PairedVersion.
 	Unpair() UnpairedVersion
 
 	// Ensures it is impossible to be both a PairedVersion and an
-	// UnpairedVersion
+	// UnpairedVersion.
 	_pair(int)
 }
 
@@ -69,7 +69,7 @@ type UnpairedVersion interface {
 	// to and unites them into a PairedVersion.
 	Pair(Revision) PairedVersion
 	// Ensures it is impossible to be both a PairedVersion and an
-	// UnpairedVersion
+	// UnpairedVersion.
 	_pair(bool)
 }
 
@@ -693,7 +693,7 @@ func compareVersionType(l, r Version) int {
 //  - Non-semver tags: footag
 //  - Revision: f6e74e8d
 //
-// Sorting for upgrade will result in the following slice.
+// Sorting for upgrade will result in the following slice:
 //
 //  [v1.1.0 v1.0.0 v1.1.0-alpha1 master devel footag f6e74e8d]
 func SortForUpgrade(vl []Version) {
@@ -726,7 +726,7 @@ func SortPairedForUpgrade(vl []PairedVersion) {
 //  - Non-semver tags: footag
 //  - Revision: f6e74e8d
 //
-// Sorting for downgrade will result in the following slice.
+// Sorting for downgrade will result in the following slice:
 //
 //  [v1.0.0 v1.1.0 v1.1.0-alpha1 footag devel master f6e74e8d]
 func SortForDowngrade(vl []Version) {
@@ -854,7 +854,7 @@ func hidePair(pvl []PairedVersion) []Version {
 	return vl
 }
 
-// VersionComponentStrings decomposes a Version into the underlying number, branch and revision
+// VersionComponentStrings decomposes a Version into the underlying number, branch and revision.
 func VersionComponentStrings(v Version) (revision string, branch string, version string) {
 	switch tv := v.(type) {
 	case UnpairedVersion: