improve doc comments

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

syft/source/all_layers_resolver.go

@@ -102,6 +102,7 @@ func (r *AllLayersResolver) FilesByPath(paths ...string) ([]Location, error) {
 }
 
 // FilesByGlob returns all file.References that match the given path glob pattern from any layer in the image.
+// nolint:gocognit
 func (r *AllLayersResolver) FilesByGlob(patterns ...string) ([]Location, error) {
 	uniqueFileIDs := file.NewFileReferenceSet()
 	uniqueLocations := make([]Location, 0)
@@ -141,6 +142,8 @@ func (r *AllLayersResolver) FilesByGlob(patterns ...string) ([]Location, error)
 	return uniqueLocations, nil
 }
 
+// RelativeFileByPath fetches a single file at the given path relative to the layer squash of the given reference.
+// This is helpful when attempting to find a file that is in the same layer or lower as another file.
 func (r *AllLayersResolver) RelativeFileByPath(location Location, path string) *Location {
 	entry, err := r.img.FileCatalog.Get(location.ref)
 	if err != nil {
@@ -157,13 +160,13 @@ func (r *AllLayersResolver) RelativeFileByPath(location Location, path string) *
 	return &relativeLocation
 }
 
-// MultipleFileContentsByRef returns the file contents for all file.References relative to the image. Note that a
+// MultipleFileContentsByLocation returns the file contents for all file.References relative to the image. Note that a
 // file.Reference is a path relative to a particular layer.
 func (r *AllLayersResolver) MultipleFileContentsByLocation(locations []Location) (map[Location]string, error) {
 	return mapLocationRefs(r.img.MultipleFileContentsByRef, locations)
 }
 
-// FileContentsByRef fetches file contents for a single file reference, irregardless of the source layer.
+// FileContentsByLocation fetches file contents for a single file reference, irregardless of the source layer.
 // If the path does not exist an error is returned.
 func (r *AllLayersResolver) FileContentsByLocation(location Location) (string, error) {
 	return r.img.FileContentsByRef(location.ref)

syft/source/directory_resolver.go

@@ -80,6 +80,9 @@ func (s DirectoryResolver) FilesByGlob(patterns ...string) ([]Location, error) {
 	return result, nil
 }
 
+// RelativeFileByPath fetches a single file at the given path relative to the layer squash of the given reference.
+// This is helpful when attempting to find a file that is in the same layer or lower as another file. For the
+// DirectoryResolver, this is a simple path lookup.
 func (s *DirectoryResolver) RelativeFileByPath(_ Location, path string) *Location {
 	paths, err := s.FilesByPath(path)
 	if err != nil {
@@ -92,7 +95,7 @@ func (s *DirectoryResolver) RelativeFileByPath(_ Location, path string) *Locatio
 	return &paths[0]
 }
 
-// MultipleFileContentsByRef returns the file contents for all file.References relative a directory.
+// MultipleFileContentsByLocation returns the file contents for all file.References relative a directory.
 func (s DirectoryResolver) MultipleFileContentsByLocation(locations []Location) (map[Location]string, error) {
 	refContents := make(map[Location]string)
 	for _, location := range locations {
@@ -106,7 +109,7 @@ func (s DirectoryResolver) MultipleFileContentsByLocation(locations []Location)
 	return refContents, nil
 }
 
-// FileContentsByRef fetches file contents for a single file reference relative to a directory.
+// FileContentsByLocation fetches file contents for a single file reference relative to a directory.
 // If the path does not exist an error is returned.
 func (s DirectoryResolver) FileContentsByLocation(location Location) (string, error) {
 	contents, err := fileContents(location.Path)

syft/source/image_metadata.go

@@ -2,6 +2,8 @@ package source
 
 import "github.com/anchore/stereoscope/pkg/image"
 
+// ImageMetadata represents all static metadata that defines what a container image is. This is useful to later describe
+// "what" was cataloged without needing the more complicated stereoscope Image objects or Resolver objects.
 type ImageMetadata struct {
 	UserInput string          `json:"userInput"`
 	Scope     Scope           `json:"scope"` // specific perspective to catalog
@@ -12,12 +14,14 @@ type ImageMetadata struct {
 	Tags      []string        `json:"tags"`
 }
 
+// LayerMetadata represents all static metadata that defines what a container image layer is.
 type LayerMetadata struct {
 	MediaType string `json:"mediaType"`
 	Digest    string `json:"digest"`
 	Size      int64  `json:"size"`
 }
 
+// NewImageMetadata creates a new ImageMetadata object populated from the given stereoscope Image object and user configuration.
 func NewImageMetadata(img *image.Image, userInput string, scope Scope) ImageMetadata {
 	// populate artifacts...
 	tags := make([]string, len(img.Metadata.Tags))

syft/source/image_squash_resolver.go

@@ -104,6 +104,9 @@ func (r *ImageSquashResolver) FilesByGlob(patterns ...string) ([]Location, error
 	return uniqueLocations, nil
 }
 
+// RelativeFileByPath fetches a single file at the given path relative to the layer squash of the given reference.
+// This is helpful when attempting to find a file that is in the same layer or lower as another file. For the
+// ImageSquashResolver, this is a simple path lookup.
 func (r *ImageSquashResolver) RelativeFileByPath(_ Location, path string) *Location {
 	paths, err := r.FilesByPath(path)
 	if err != nil {
@@ -116,13 +119,13 @@ func (r *ImageSquashResolver) RelativeFileByPath(_ Location, path string) *Locat
 	return &paths[0]
 }
 
-// MultipleFileContentsByRef returns the file contents for all file.References relative to the image. Note that a
+// MultipleFileContentsByLocation returns the file contents for all file.References relative to the image. Note that a
 // file.Reference is a path relative to a particular layer, in this case only from the squashed representation.
 func (r *ImageSquashResolver) MultipleFileContentsByLocation(locations []Location) (map[Location]string, error) {
 	return mapLocationRefs(r.img.MultipleFileContentsByRef, locations)
 }
 
-// FileContentsByRef fetches file contents for a single file reference, irregardless of the source layer.
+// FileContentsByLocation fetches file contents for a single file reference, irregardless of the source layer.
 // If the path does not exist an error is returned.
 func (r *ImageSquashResolver) FileContentsByLocation(location Location) (string, error) {
 	return r.img.FileContentsByRef(location.ref)

syft/source/location.go

@@ -7,18 +7,21 @@ import (
 	"github.com/anchore/stereoscope/pkg/image"
 )
 
+// Location represents a path relative to a particular filesystem.
 type Location struct {
-	Path         string `json:"path"`
-	FileSystemID string `json:"layerID,omitempty"` // TODO: comment
-	ref          file.Reference
+	Path         string         `json:"path"`              // The string path of the location (e.g. /etc/hosts)
+	FileSystemID string         `json:"layerID,omitempty"` // An ID representing the filesystem. For container images this is a layer digest, directories or root filesystem this is blank.
+	ref          file.Reference // The file reference relative to the stereoscope.FileCatalog that has more information about this location.
 }
 
+// NewLocation creates a new Location representing a path without denoting a filesystem or FileCatalog reference.
 func NewLocation(path string) Location {
 	return Location{
 		Path: path,
 	}
 }
 
+// NewLocationFromImage creates a new Location representing the given path (extracted from the ref) relative to the given image.
 func NewLocationFromImage(ref file.Reference, img *image.Image) Location {
 	entry, err := img.FileCatalog.Get(ref)
 	if err != nil {

syft/source/metadata.go

@@ -1,5 +1,6 @@
 package source
 
+// Metadata represents any static source data that helps describe "what" was cataloged.
 type Metadata struct {
 	Scheme        Scheme        // the source data scheme type (directory or image)
 	ImageMetadata ImageMetadata // all image info (image only)

syft/source/resolver.go

@@ -19,7 +19,7 @@ type ContentResolver interface {
 	// TODO: we should consider refactoring to return a set of io.Readers or file.Openers instead of the full contents themselves (allow for optional buffering).
 }
 
-//  FileResolver knows how to get file.References for given string paths and globs
+// FileResolver knows how to get file.References for given string paths and globs
 type FileResolver interface {
 	// FilesByPath fetches a set of file references which have the given path (for an image, there may be multiple matches)
 	FilesByPath(paths ...string) ([]Location, error)

syft/source/scheme.go

@@ -9,12 +9,16 @@ import (
 	"github.com/spf13/afero"
 )
 
+// Scheme represents the optional prefixed string at the beginning of a user request (e.g. "docker:").
 type Scheme string
 
 const (
-	UnknownScheme   Scheme = "unknown-scheme"
-	DirectoryScheme Scheme = "directory-scheme"
-	ImageScheme     Scheme = "image-scheme"
+	// UnknownScheme is the default scheme
+	UnknownScheme Scheme = "UnknownScheme"
+	// DirectoryScheme indicates the source being cataloged is a directory on the root filesystem
+	DirectoryScheme Scheme = "DirectoryScheme"
+	// ImageScheme indicates the source being cataloged is a container image
+	ImageScheme Scheme = "ImageScheme"
 )
 
 func detectScheme(fs afero.Fs, imageDetector sourceDetector, userInput string) (Scheme, string, error) {

syft/source/scope.go

@@ -2,19 +2,25 @@ package source
 
 import "strings"
 
+// Scope indicates "how" or from "which perspectives" the source object should be cataloged from.
 type Scope string
 
 const (
-	UnknownScope   Scope = "UnknownScope"
-	SquashedScope  Scope = "Squashed"
+	// UnknownScope is the default scope
+	UnknownScope Scope = "UnknownScope"
+	// SquashedScope indicates to only catalog content visible from the squashed filesystem representation (what can be seen only within the container at runtime)
+	SquashedScope Scope = "Squashed"
+	// AllLayersScope indicates to catalog content on all layers, irregardless if it is visible from the container at runtime.
 	AllLayersScope Scope = "AllLayers"
 )
 
+// AllScopes is a slice containing all possible scope options
 var AllScopes = []Scope{
 	SquashedScope,
 	AllLayersScope,
 }
 
+// ParseScope returns a scope as indicated from the given string.
 func ParseScope(userStr string) Scope {
 	switch strings.ToLower(userStr) {
 	case strings.ToLower(SquashedScope.String()):