improve doc comments

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

internal/constants.go

@@ -1,4 +1,4 @@
 package internal
 
-// note: do not change this
+// ApplicationName is the non-capitalized name of the application (do not change this)
 const ApplicationName = "syft"

internal/docs.go

@@ -0,0 +1,4 @@
+/*
+Package internal contains miscellaneous functions and objects useful within syft but should not be used externally.
+*/
+package internal

internal/file/glob_match.go

@@ -1,5 +1,6 @@
 package file
 
+// GlobMatch evaluates the given glob pattern against the given "name" string, indicating if there is a match or not.
 // Source: https://research.swtch.com/glob.go
 func GlobMatch(pattern, name string) bool {
 	px := 0

internal/file/opener.go

@@ -5,10 +5,12 @@ import (
 	"os"
 )
 
+// Opener is an object that stores a path to later be opened as a file.
 type Opener struct {
 	path string
 }
 
+// Open the stored path as a io.ReadCloser.
 func (o Opener) Open() (io.ReadCloser, error) {
 	return os.Open(o.path)
 }

internal/file/zip_file_manifest.go

@@ -12,16 +12,20 @@ import (
 	"github.com/anchore/syft/internal/log"
 )
 
+// ZipFileManifest is a collection of paths and their file metadata.
 type ZipFileManifest map[string]os.FileInfo
 
+// newZipManifest creates an empty ZipFileManifest.
 func newZipManifest() ZipFileManifest {
 	return make(ZipFileManifest)
 }
 
+// Add a new path and it's file metadata to the collection.
 func (z ZipFileManifest) Add(entry string, info os.FileInfo) {
 	z[entry] = info
 }
 
+// GlobMatch returns the path keys that match the given value(s).
 func (z ZipFileManifest) GlobMatch(patterns ...string) []string {
 	uniqueMatches := internal.NewStringSet()
 
@@ -43,6 +47,7 @@ func (z ZipFileManifest) GlobMatch(patterns ...string) []string {
 	return results
 }
 
+// NewZipFileManifest creates and returns a new ZipFileManifest populated with path and metadata from the given zip archive path.
 func NewZipFileManifest(archivePath string) (ZipFileManifest, error) {
 	zipReader, err := zip.OpenReader(archivePath)
 	manifest := newZipManifest()
@@ -62,6 +67,7 @@ func NewZipFileManifest(archivePath string) (ZipFileManifest, error) {
 	return manifest, nil
 }
 
+// normalizeZipEntryName takes the given path entry and ensures it is prefixed with "/".
 func normalizeZipEntryName(entry string) string {
 	if !strings.HasPrefix(entry, "/") {
 		return "/" + entry

internal/file/zip_file_traversal.go

@@ -15,6 +15,7 @@ import (
 )
 
 const (
+	// represents the order of bytes
 	_  = iota
 	KB = 1 << (10 * iota)
 	MB
@@ -33,6 +34,7 @@ func newZipTraverseRequest(paths ...string) zipTraversalRequest {
 	return results
 }
 
+// TraverseFilesInZip enumerates all paths stored within a zip archive using the visitor pattern.
 func TraverseFilesInZip(archivePath string, visitor func(*zip.File) error, paths ...string) error {
 	request := newZipTraverseRequest(paths...)
 
@@ -63,6 +65,7 @@ func TraverseFilesInZip(archivePath string, visitor func(*zip.File) error, paths
 	return nil
 }
 
+// ExtractFromZipToUniqueTempFile extracts select paths for the given archive to a temporary directory, returning file openers for each file extracted.
 func ExtractFromZipToUniqueTempFile(archivePath, dir string, paths ...string) (map[string]Opener, error) {
 	results := make(map[string]Opener)
 
@@ -121,6 +124,7 @@ func ExtractFromZipToUniqueTempFile(archivePath, dir string, paths ...string) (m
 	return results, TraverseFilesInZip(archivePath, visitor, paths...)
 }
 
+// ContentsFromZip extracts select paths for the given archive and returns a set of string contents for each path.
 func ContentsFromZip(archivePath string, paths ...string) (map[string]string, error) {
 	results := make(map[string]string)
 
@@ -162,6 +166,7 @@ func ContentsFromZip(archivePath string, paths ...string) (map[string]string, er
 	return results, TraverseFilesInZip(archivePath, visitor, paths...)
 }
 
+// UnzipToDir extracts a zip archive to a target directory.
 func UnzipToDir(archivePath, targetDir string) error {
 	visitor := func(file *zip.File) error {
 		// the zip-slip attack protection is still being erroneously detected

internal/format/color.go

@@ -1,21 +0,0 @@
-package format
-
-import "fmt"
-
-const (
-	DefaultColor Color = iota + 30
-	Red
-	Green
-	Yellow
-	Blue
-	Magenta
-	Cyan
-	White
-)
-
-type Color uint8
-
-// TODO: not cross platform (windows...)
-func (c Color) Format(s string) string {
-	return fmt.Sprintf("\x1b[%dm%s\x1b[0m", c, s)
-}

internal/log/log.go

@@ -1,37 +1,49 @@
+/*
+Package log contains the singleton object and helper functions for facilitating logging within the syft library.
+*/
 package log
 
 import "github.com/anchore/syft/syft/logger"
 
+// Log is the singleton used to facilitate logging internally within syft
 var Log logger.Logger = &nopLogger{}
 
+// Errorf takes a formatted template string and template arguments for the error logging level.
 func Errorf(format string, args ...interface{}) {
 	Log.Errorf(format, args...)
 }
 
+// Error logs the given arguments at the error logging level.
 func Error(args ...interface{}) {
 	Log.Error(args...)
 }
 
+// Warnf takes a formatted template string and template arguments for the warning logging level.
 func Warnf(format string, args ...interface{}) {
 	Log.Warnf(format, args...)
 }
 
+// Warn logs the given arguments at the warning logging level.
 func Warn(args ...interface{}) {
 	Log.Warn(args...)
 }
 
+// Infof takes a formatted template string and template arguments for the info logging level.
 func Infof(format string, args ...interface{}) {
 	Log.Infof(format, args...)
 }
 
+// Info logs the given arguments at the info logging level.
 func Info(args ...interface{}) {
 	Log.Info(args...)
 }
 
+// Debugf takes a formatted template string and template arguments for the debug logging level.
 func Debugf(format string, args ...interface{}) {
 	Log.Debugf(format, args...)
 }
 
+// Debug logs the given arguments at the debug logging level.
 func Debug(args ...interface{}) {
 	Log.Debug(args...)
 }

internal/logger/doc.go

@@ -0,0 +1,4 @@
+/*
+Package logger contains implementations for the syft.logger.Logger interface.
+*/
+package logger

internal/logger/logrus.go

@@ -10,6 +10,7 @@ import (
 	prefixed "github.com/x-cray/logrus-prefixed-formatter"
 )
 
+// LogrusConfig contains all configurable values for the Logrus logger
 type LogrusConfig struct {
 	EnableConsole bool
 	EnableFile    bool
@@ -18,16 +19,19 @@ type LogrusConfig struct {
 	FileLocation  string
 }
 
+// LogrusLogger contains all runtime values for using Logrus with the configured output target and input configuration values.
 type LogrusLogger struct {
 	Config LogrusConfig
 	Logger *logrus.Logger
 	Output io.Writer
 }
 
+// LogrusNestedLogger is a wrapper for Logrus to enable nested logging configuration (loggers that always attach key-value pairs to all log entries)
 type LogrusNestedLogger struct {
 	Logger *logrus.Entry
 }
 
+// NewLogrusLogger creates a new LogrusLogger with the given configuration
 func NewLogrusLogger(cfg LogrusConfig) *LogrusLogger {
 	appLogger := logrus.New()
 
@@ -76,66 +80,82 @@ func NewLogrusLogger(cfg LogrusConfig) *LogrusLogger {
 	}
 }
 
+// Debugf takes a formatted template string and template arguments for the debug logging level.
 func (l *LogrusLogger) Debugf(format string, args ...interface{}) {
 	l.Logger.Debugf(format, args...)
 }
 
+// Infof takes a formatted template string and template arguments for the info logging level.
 func (l *LogrusLogger) Infof(format string, args ...interface{}) {
 	l.Logger.Infof(format, args...)
 }
 
+// Warnf takes a formatted template string and template arguments for the warning logging level.
 func (l *LogrusLogger) Warnf(format string, args ...interface{}) {
 	l.Logger.Warnf(format, args...)
 }
 
+// Errorf takes a formatted template string and template arguments for the error logging level.
 func (l *LogrusLogger) Errorf(format string, args ...interface{}) {
 	l.Logger.Errorf(format, args...)
 }
 
+// Debug logs the given arguments at the debug logging level.
 func (l *LogrusLogger) Debug(args ...interface{}) {
 	l.Logger.Debug(args...)
 }
 
+// Info logs the given arguments at the info logging level.
 func (l *LogrusLogger) Info(args ...interface{}) {
 	l.Logger.Info(args...)
 }
 
+// Warn logs the given arguments at the warning logging level.
 func (l *LogrusLogger) Warn(args ...interface{}) {
 	l.Logger.Warn(args...)
 }
 
+// Error logs the given arguments at the error logging level.
 func (l *LogrusLogger) Error(args ...interface{}) {
 	l.Logger.Error(args...)
 }
 
+// Debugf takes a formatted template string and template arguments for the debug logging level.
 func (l *LogrusNestedLogger) Debugf(format string, args ...interface{}) {
 	l.Logger.Debugf(format, args...)
 }
 
+// Infof takes a formatted template string and template arguments for the info logging level.
 func (l *LogrusNestedLogger) Infof(format string, args ...interface{}) {
 	l.Logger.Infof(format, args...)
 }
 
+// Warnf takes a formatted template string and template arguments for the warning logging level.
 func (l *LogrusNestedLogger) Warnf(format string, args ...interface{}) {
 	l.Logger.Warnf(format, args...)
 }
 
+// Errorf takes a formatted template string and template arguments for the error logging level.
 func (l *LogrusNestedLogger) Errorf(format string, args ...interface{}) {
 	l.Logger.Errorf(format, args...)
 }
 
+// Debug logs the given arguments at the debug logging level.
 func (l *LogrusNestedLogger) Debug(args ...interface{}) {
 	l.Logger.Debug(args...)
 }
 
+// Info logs the given arguments at the info logging level.
 func (l *LogrusNestedLogger) Info(args ...interface{}) {
 	l.Logger.Info(args...)
 }
 
+// Warn logs the given arguments at the warning logging level.
 func (l *LogrusNestedLogger) Warn(args ...interface{}) {
 	l.Logger.Warn(args...)
 }
 
+// Error logs the given arguments at the error logging level.
 func (l *LogrusNestedLogger) Error(args ...interface{}) {
 	l.Logger.Error(args...)
 }

internal/stringset.go

@@ -1,11 +1,16 @@
 package internal
 
+import "sort"
+
+// StringSet represents a set of string types.
 type StringSet map[string]struct{}
 
+// NewStringSet creates a new empty StringSet.
 func NewStringSet() StringSet {
 	return make(StringSet)
 }
 
+// NewStringSetFromSlice creates a StringSet populated with values from the given slice.
 func NewStringSetFromSlice(start []string) StringSet {
 	ret := make(StringSet)
 	for _, s := range start {
@@ -14,19 +19,23 @@ func NewStringSetFromSlice(start []string) StringSet {
 	return ret
 }
 
+// Add a string to the set.
 func (s StringSet) Add(i string) {
 	s[i] = struct{}{}
 }
 
+// Remove a string from the set.
 func (s StringSet) Remove(i string) {
 	delete(s, i)
 }
 
+// Contains indicates if the given string is contained within the set.
 func (s StringSet) Contains(i string) bool {
 	_, ok := s[i]
 	return ok
 }
 
+// ToSlice returns a sorted slice of strings that are contained within the set.
 func (s StringSet) ToSlice() []string {
 	ret := make([]string, len(s))
 	idx := 0
@@ -34,5 +43,6 @@ func (s StringSet) ToSlice() []string {
 		ret[idx] = v
 		idx++
 	}
+	sort.Strings(ret)
 	return ret
 }

internal/version/build.go

@@ -1,3 +1,6 @@
+/*
+Package version contains all build time metadata (version, build time, git commit, etc).
+*/
 package version
 
 import (

internal/version/update.go

@@ -18,6 +18,7 @@ var latestAppVersionURL = struct {
 	path: fmt.Sprintf("/%s/releases/latest/VERSION", internal.ApplicationName),
 }
 
+// IsUpdateAvailable indicates if there is a newer application version available, and if so, what the new version is.
 func IsUpdateAvailable() (bool, string, error) {
 	currentVersionStr := FromBuild().Version
 	currentVersion, err := hashiVersion.NewVersion(currentVersionStr)