Improve overall documentation (#148)

* improve overall documentation

Signed-off-by: Alex Goodman <alex.goodman@anchore.com>

* fix tests to use scope.Resolver over scope

Signed-off-by: Alex Goodman <alex.goodman@anchore.com>

syft/pkg/catalog.go

@@ -12,6 +12,7 @@ import (
 
 var nextPackageID int64
 
+// Catalog represents a collection of Packages.
 type Catalog struct {
 	byID   map[ID]*Package
 	byType map[Type][]*Package
@@ -19,6 +20,7 @@ type Catalog struct {
 	lock   sync.RWMutex
 }
 
+// NewCatalog returns a new empty Catalog
 func NewCatalog() *Catalog {
 	return &Catalog{
 		byID:   make(map[ID]*Package),
@@ -27,18 +29,22 @@ func NewCatalog() *Catalog {
 	}
 }
 
+// PackageCount returns the total number of packages that have been added.
 func (c *Catalog) PackageCount() int {
 	return len(c.byID)
 }
 
+// Package returns the package with the given ID.
 func (c *Catalog) Package(id ID) *Package {
 	return c.byID[id]
 }
 
+// PackagesByFile returns all packages that were discovered from the given source file reference.
 func (c *Catalog) PackagesByFile(ref file.Reference) []*Package {
 	return c.byFile[ref]
 }
 
+// Add a package to the Catalog.
 func (c *Catalog) Add(p Package) {
 	if p.id != 0 {
 		log.Errorf("package already added to catalog: %s", p)
@@ -70,6 +76,7 @@ func (c *Catalog) Add(p Package) {
 	}
 }
 
+// Enumerate all packages for the given type(s), enumerating all packages if no type is specified.
 func (c *Catalog) Enumerate(types ...Type) <-chan *Package {
 	channel := make(chan *Package)
 	go func() {
@@ -96,6 +103,8 @@ func (c *Catalog) Enumerate(types ...Type) <-chan *Package {
 	return channel
 }
 
+// Sorted enumerates all packages for the given types sorted by package name. Enumerates all packages if no type
+// is specified.
 func (c *Catalog) Sorted(types ...Type) []*Package {
 	pkgs := make([]*Package, 0)
 	for p := range c.Enumerate(types...) {

syft/pkg/metadata.go

@@ -9,7 +9,7 @@ type DpkgMetadata struct {
 	// TODO: consider keeping the remaining values as an embedded map
 }
 
-// RpmMetadata represents all captured data for a RHEL package DB entry.
+// RpmMetadata represents all captured data for a RPM DB package entry.
 type RpmMetadata struct {
 	Version   string `mapstructure:"Version" json:"version"`
 	Epoch     int    `mapstructure:"Epoch" json:"epoch"`
@@ -21,6 +21,7 @@ type RpmMetadata struct {
 	Vendor    string `mapstructure:"Vendor" json:"vendor"`
 }
 
+// JavaManifest represents the fields of interest extracted from a Java archive's META-INF/MANIFEST.MF file.
 type JavaManifest struct {
 	Name            string            `mapstructure:"Name" json:"name"`
 	ManifestVersion string            `mapstructure:"Manifest-Version" json:"manifest-version"`
@@ -33,6 +34,7 @@ type JavaManifest struct {
 	Extra           map[string]string `mapstructure:",remain" json:"extra-fields"`
 }
 
+// PomProperties represents the fields of interest extracted from a Java archive's pom.xml file.
 type PomProperties struct {
 	Path       string
 	Name       string            `mapstructure:"name" json:"name"`
@@ -42,13 +44,14 @@ type PomProperties struct {
 	Extra      map[string]string `mapstructure:",remain" json:"extra-fields"`
 }
 
+// JavaMetadata encapsulates all Java ecosystem metadata for a package as well as an (optional) parent relationship.
 type JavaMetadata struct {
 	Manifest      *JavaManifest  `mapstructure:"Manifest" json:"manifest"`
 	PomProperties *PomProperties `mapstructure:"PomProperties" json:"pom-properties"`
 	Parent        *Package       `json:"parent-package"`
 }
 
-// source: https://wiki.alpinelinux.org/wiki/Apk_spec
+// ApkMetadata represents all captured data for a Alpine DB package entry. See https://wiki.alpinelinux.org/wiki/Apk_spec for more information.
 type ApkMetadata struct {
 	Package          string          `mapstructure:"P" json:"package"`
 	OriginPackage    string          `mapstructure:"o" json:"origin-package"`
@@ -66,6 +69,7 @@ type ApkMetadata struct {
 	Files            []ApkFileRecord `json:"files"`
 }
 
+// ApkFileRecord represents a single file listing and metadata from a APK DB entry (which may have many of these file records).
 type ApkFileRecord struct {
 	Path        string `json:"path"`
 	OwnerUID    string `json:"owner-uid"`

syft/pkg/package.go

@@ -1,3 +1,6 @@
+/*
+Package pkg provides the data structures for a package, a package catalog, package types, and domain-specific metadata.
+*/
 package pkg
 
 import (
@@ -8,25 +11,26 @@ import (
 
 type ID int64
 
-// TODO: add field to trace which cataloger detected this
-
-// Package represents an application or library that has been bundled into a distributable format
+// Package represents an application or library that has been bundled into a distributable format.
 type Package struct {
-	id       ID               // this is set when a package is added to the catalog
-	Name     string           `json:"manifest"`
-	Version  string           `json:"version"`
-	FoundBy  string           `json:"found-by"` // FoundBy is the cataloger that discovered this package
-	Source   []file.Reference `json:"sources"`
-	Licenses []string         `json:"licenses"` // TODO: should we move this into metadata?
-	Language Language         `json:"language"` // TODO: should this support multiple languages as a slice?
-	Type     Type             `json:"type"`
-	Metadata interface{}      `json:"metadata,omitempty"`
+	id      ID               // uniquely identifies a package, set by the cataloger
+	Name    string           `json:"manifest"` // the package name
+	Version string           `json:"version"`  // the version of the package
+	FoundBy string           `json:"found-by"` // the specific cataloger that discovered this package
+	Source  []file.Reference `json:"sources"`  // the locations that lead to the discovery of this package (note: this is not necessarily the locations that make up this package)
+	// TODO: should we move licenses into metadata?
+	Licenses []string    `json:"licenses"`           // licenses discovered with the package metadata
+	Language Language    `json:"language"`           // the language ecosystem this package belongs to (e.g. JavaScript, Python, etc)
+	Type     Type        `json:"type"`               // the package type (e.g. Npm, Yarn, Egg, Wheel, Rpm, Deb, etc)
+	Metadata interface{} `json:"metadata,omitempty"` // additional data found while parsing the package source
 }
 
+// ID returns the package ID, which is unique relative to a package catalog.
 func (p Package) ID() ID {
 	return p.id
 }
 
+// Stringer to represent a package.
 func (p Package) String() string {
 	return fmt.Sprintf("Pkg(type=%s, name=%s, version=%s)", p.Type, p.Name, p.Version)
 }

syft/pkg/type.go

@@ -1,5 +1,6 @@
 package pkg
 
+// Type represents a Package Type for or within a language ecosystem (there may be multiple package types within a language ecosystem)
 type Type string
 
 const (