add helpful comments

beyang · beyang · commit ef2ad47e3f89 · 2014-04-01T15:08:55.000-07:00
diff --git a/py.go b/py.go
@@ -12,6 +12,7 @@ type Requirement struct {
 	Version    string
 }
 
+// Parse requirements from a raw string in the requirements format expected by pip (e.g., in requirements.txt)
 func ParseRequirements(rawReqs string) ([]*Requirement, error) {
 	rawReqs = strings.TrimSpace(rawReqs)
 
@@ -33,6 +34,7 @@ func ParseRequirements(rawReqs string) ([]*Requirement, error) {
 	return reqs, nil
 }
 
+// Parse a single raw requirement, e.g., from "flask=1.0.1"
 func ParseRequirement(reqStr string) (*Requirement, error) {
 	reqStr = strings.TrimSpace(reqStr)
 	match := requirementRegexp.FindStringSubmatch(reqStr)
@@ -48,6 +50,7 @@ func ParseRequirement(reqStr string) (*Requirement, error) {
 	}, nil
 }
 
+// Normalizes package names so they are comparable
 func NormalizedPkgName(pkg string) string {
 	return strings.ToLower(pkg)
 }
diff --git a/pypi.go b/pypi.go
@@ -2,13 +2,14 @@ package cheerio
 
 import (
 	"fmt"
-	"github.com/beyang/cheerio/util"
-	"github.com/beyang/go-version"
 	"io/ioutil"
 	"net/http"
 	"path/filepath"
 	"regexp"
 	"strings"
+
+	"github.com/beyang/cheerio/util"
+	"github.com/beyang/go-version"
 )
 
 var DefaultPyPI = &PackageIndex{URI: "https://pypi.python.org"}
@@ -17,6 +18,7 @@ type PackageIndex struct {
 	URI string
 }
 
+// Get names of all packages served by a PyPI server.
 func (p *PackageIndex) AllPackages() ([]string, error) {
 	pkgs := make([]string, 0)
 
diff --git a/repo.go b/repo.go
@@ -14,6 +14,9 @@ var repoPatterns = []*regexp.Regexp{
 
 var pkgInfoPattern = regexp.MustCompile(`(?:[^/]+/)*PKG\-INFO`)
 
+// Returns the source repository URL for a given PyPI package. This information is not explicitly specified anywhere in PyPI metadata, so try to infer
+// it by doing the following: First, check if it is hardcoded below. If not, then fetch the metadata from the PyPI server and check if the website
+// (specified in the metdata) pattern matches a repository URL.
 func (p *PackageIndex) FetchSourceRepoURL(pkg string) (string, error) {
 	b, err := p.FetchRawMetadata(pkg, pkgInfoPattern, pkgInfoPattern, pkgInfoPattern)
 	if err != nil {
diff --git a/req.go b/req.go
@@ -28,11 +28,13 @@ func init() {
 	}
 }
 
+// Dependency graph over repositories in a given Python Package Index.
 type PyPIGraph struct {
 	Req   map[string][]string
 	ReqBy map[string][]string
 }
 
+// Deserializes a PyPIGraph stored in a file
 func NewPyPIGraph(file string) (*PyPIGraph, error) {
 	var graph *PyPIGraph
 
diff --git a/toplevel.go b/toplevel.go
@@ -7,6 +7,8 @@ import (
 
 var topLevelTxtPattern = regexp.MustCompile(`(?:[^/]+/)*(?:[^/]*\.egg\-info/top_level\.txt)`)
 
+// Returns the top-level modules for a given PyPI package. This information is typically stored in the PyPI metadata, which is fetched from the remote
+// PyPI server. In some cases where the information is unavailable in the metadata, it has been hard-coded below.
 func (p *PackageIndex) FetchSourceTopLevelModules(pkg string) ([]string, error) {
 	b, err := p.FetchRawMetadata(pkg, topLevelTxtPattern, topLevelTxtPattern, topLevelTxtPattern)
 	if err != nil {

Original file line number	Diff line number	Diff line change
`@@ -12,6 +12,7 @@ type Requirement struct {`
`12`	`12`	`Version string`
`13`	`13`	`}`
`14`	`14`
	`15`	`+// Parse requirements from a raw string in the requirements format expected by pip (e.g., in requirements.txt)`
`15`	`16`	`func ParseRequirements(rawReqs string) ([]*Requirement, error) {`
`16`	`17`	`rawReqs = strings.TrimSpace(rawReqs)`
`17`	`18`
`@@ -33,6 +34,7 @@ func ParseRequirements(rawReqs string) ([]*Requirement, error) {`
`33`	`34`	`return reqs, nil`
`34`	`35`	`}`
`35`	`36`
	`37`	`+// Parse a single raw requirement, e.g., from "flask=1.0.1"`
`36`	`38`	`func ParseRequirement(reqStr string) (*Requirement, error) {`
`37`	`39`	`reqStr = strings.TrimSpace(reqStr)`
`38`	`40`	`match := requirementRegexp.FindStringSubmatch(reqStr)`
`@@ -48,6 +50,7 @@ func ParseRequirement(reqStr string) (*Requirement, error) {`
`48`	`50`	`}, nil`
`49`	`51`	`}`
`50`	`52`
	`53`	`+// Normalizes package names so they are comparable`
`51`	`54`	`func NormalizedPkgName(pkg string) string {`
`52`	`55`	`return strings.ToLower(pkg)`
`53`	`56`	`}`
Original file line number	Diff line number	Diff line change
`@@ -28,11 +28,13 @@ func init() {`
`28`	`28`	`}`
`29`	`29`	`}`
`30`	`30`
	`31`	`+// Dependency graph over repositories in a given Python Package Index.`
`31`	`32`	`type PyPIGraph struct {`
`32`	`33`	`Req map[string][]string`
`33`	`34`	`ReqBy map[string][]string`
`34`	`35`	`}`
`35`	`36`
	`37`	`+// Deserializes a PyPIGraph stored in a file`
`36`	`38`	`func NewPyPIGraph(file string) (*PyPIGraph, error) {`
`37`	`39`	`var graph *PyPIGraph`
`38`	`40`