improve doc comments

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

syft/pkg/apk_metadata.go

@@ -35,6 +35,7 @@ type ApkFileRecord struct {
 	Checksum    string `json:"checksum,omitempty"`
 }
 
+// PackageURL returns the PURL for the specific Alpine package (see https://github.com/package-url/purl-spec)
 func (m ApkMetadata) PackageURL() string {
 	pURL := packageurl.NewPackageURL(
 		// note: this is currently a candidate and not technically within spec

syft/pkg/dpkg_metadata.go

@@ -17,11 +17,13 @@ type DpkgMetadata struct {
 	Files         []DpkgFileRecord `json:"files"`
 }
 
+// DpkgFileRecord represents a single file attributed to a debian package.
 type DpkgFileRecord struct {
 	Path string `json:"path"`
 	MD5  string `json:"md5"`
 }
 
+// PackageURL returns the PURL for the specific Debian package (see https://github.com/package-url/purl-spec)
 func (m DpkgMetadata) PackageURL(d distro.Distro) string {
 	pURL := packageurl.NewPackageURL(
 		// TODO: replace with `packageurl.TypeDebian` upon merge of https://github.com/package-url/packageurl-go/pull/21

syft/pkg/gem_metadata.go

@@ -1,5 +1,6 @@
 package pkg
 
+// GemMetadata represents all metadata parsed from the gemspec file
 type GemMetadata struct {
 	Name     string   `mapstructure:"name" json:"name"`
 	Version  string   `mapstructure:"version" json:"version"`

syft/pkg/java_metadata.go

@@ -26,6 +26,7 @@ type JavaManifest struct {
 	NamedSections map[string]map[string]string `json:"namedSections,omitempty"`
 }
 
+// PackageURL returns the PURL for the specific Alpine package (see https://github.com/package-url/purl-spec)
 func (m JavaMetadata) PackageURL() string {
 	if m.PomProperties != nil {
 		pURL := packageurl.NewPackageURL(

syft/pkg/language.go

@@ -1,8 +1,10 @@
 package pkg
 
+// Language represents a single programming language.
 type Language string
 
 const (
+	// the full set of supported programming languages
 	UnknownLanguage Language = "UnknownLanguage"
 	Java            Language = "java"
 	JavaScript      Language = "javascript"
@@ -11,6 +13,7 @@ const (
 	Go              Language = "go"
 )
 
+// AllLanguages is a set of all programming languages detected by syft.
 var AllLanguages = []Language{
 	Java,
 	JavaScript,
@@ -19,6 +22,7 @@ var AllLanguages = []Language{
 	Go,
 }
 
+// String returns the string representation of the language.
 func (l Language) String() string {
 	return string(l)
 }

syft/pkg/metadata.go

@@ -1,14 +1,16 @@
 package pkg
 
+// MetadataType represents the data shape stored within pkg.Package.Metadata.
 type MetadataType string
 
 const (
+	// this is the full set of data shapes that can be represented within the pkg.Package.Metadata field
 	UnknownMetadataType        MetadataType = "UnknownMetadata"
-	ApkMetadataType            MetadataType = "apk-metadata"
-	DpkgMetadataType           MetadataType = "dpkg-metadata"
-	GemMetadataType            MetadataType = "gem-metadata"
-	JavaMetadataType           MetadataType = "java-metadata"
-	NpmPackageJSONMetadataType MetadataType = "npm-package-json-metadata"
-	RpmdbMetadataType          MetadataType = "rpmdb-metadata"
-	PythonPackageMetadataType  MetadataType = "python-package-metadata"
+	ApkMetadataType            MetadataType = "ApkMetadata"
+	DpkgMetadataType           MetadataType = "DpkgMetadata"
+	GemMetadataType            MetadataType = "GemMetadata"
+	JavaMetadataType           MetadataType = "JavaMetadata"
+	NpmPackageJSONMetadataType MetadataType = "NpmPackageJsonMetadata"
+	RpmdbMetadataType          MetadataType = "RpmdbMetadata"
+	PythonPackageMetadataType  MetadataType = "PythonPackageMetadata"
 )

syft/pkg/package.go

@@ -14,6 +14,7 @@ import (
 	"github.com/package-url/packageurl-go"
 )
 
+// ID represents a unique value for each package added to a package catalog.
 type ID int64
 
 // Package represents an application or library that has been bundled into a distributable format.

syft/pkg/python_package_metadata.go

@@ -1,15 +1,16 @@
 package pkg
 
-type Digest struct {
+// PythonFileDigest represents the file metadata for a single file attributed to a python package.
+type PythonFileDigest struct {
 	Algorithm string `json:"algorithm"`
 	Value     string `json:"value"`
 }
 
 // PythonFileRecord represents a single entry within a RECORD file for a python wheel or egg package
 type PythonFileRecord struct {
-	Path   string  `json:"path"`
-	Digest *Digest `json:"digest,omitempty"`
-	Size   string  `json:"size,omitempty"`
+	Path   string            `json:"path"`
+	Digest *PythonFileDigest `json:"digest,omitempty"`
+	Size   string            `json:"size,omitempty"`
 }
 
 // PythonPackageMetadata represents all captured data for a python egg or wheel package.

syft/pkg/rpmdb_metadata.go

@@ -21,6 +21,7 @@ type RpmdbMetadata struct {
 	Files     []RpmdbFileRecord `json:"files"`
 }
 
+// RpmdbFileRecord represents the file metadata for a single file attributed to a RPM package.
 type RpmdbFileRecord struct {
 	Path   string        `json:"path"`
 	Mode   RpmdbFileMode `json:"mode"`
@@ -28,8 +29,10 @@ type RpmdbFileRecord struct {
 	SHA256 string        `json:"sha256"`
 }
 
+// RpmdbFileMode is the raw file mode for a single file. This can be interpreted as the linux stat.h mode (see https://pubs.opengroup.org/onlinepubs/007908799/xsh/sysstat.h.html)
 type RpmdbFileMode uint16
 
+// PackageURL returns the PURL for the specific RHEL package (see https://github.com/package-url/purl-spec)
 func (m RpmdbMetadata) PackageURL(d distro.Distro) string {
 	pURL := packageurl.NewPackageURL(
 		packageurl.TypeRPM,

syft/pkg/type.go

@@ -6,6 +6,7 @@ import "github.com/package-url/packageurl-go"
 type Type string
 
 const (
+	// the full set of supported packages
 	UnknownPkg       Type = "UnknownPackage"
 	ApkPkg           Type = "apk"
 	GemPkg           Type = "gem"
@@ -18,6 +19,7 @@ const (
 	GoModulePkg      Type = "go-module"
 )
 
+// AllPkgs represents all supported package types
 var AllPkgs = []Type{
 	ApkPkg,
 	GemPkg,
@@ -30,6 +32,7 @@ var AllPkgs = []Type{
 	GoModulePkg,
 }
 
+// PackageURLType returns the PURL package type for the current package.
 func (t Type) PackageURLType() string {
 	switch t {
 	case ApkPkg: