Address TODOs by adding comments

Signed-off-by: Natalie Arellano <[email protected]>

buildpack/build.go

@@ -56,7 +56,9 @@ type BuildOutputs struct {
 	Slices      []layers.Slice
 }
 
-// BuildExecutor TODO
+// BuildExecutor executes a single buildpack's `./bin/build` binary,
+// providing inputs as defined in the Buildpack Interface Specification,
+// and processing outputs for the platform.
 //
 //go:generate mockgen -package testmock -destination ../phase/testmock/build_executor.go github.com/buildpacks/lifecycle/buildpack BuildExecutor
 type BuildExecutor interface {

buildpack/descriptor.go

@@ -5,7 +5,8 @@ const (
 	KindExtension = "Extension"
 )
 
-// Descriptor TODO
+// Descriptor exposes information contained in a buildpack.toml or extension.toml
+// that is generic to buildpacks and/or image extensions.
 //
 //go:generate mockgen -package testmock -destination ../lifecycle/testmock/component_descriptor.go github.com/buildpacks/lifecycle/buildpack Descriptor
 type Descriptor interface {

buildpack/detect.go

@@ -39,7 +39,10 @@ type DetectOutputs struct {
 	Err    error  `toml:"-"`
 }
 
-// DetectExecutor TODO
+// DetectExecutor executes a single buildpack or image extension's `./bin/detect` binary,
+// providing inputs as defined in the Buildpack Interface Specification,
+// and processing outputs for the platform.
+// For image extensions (where `./bin/detect` is optional), pre-populated outputs are processed here.
 //
 //go:generate mockgen -package testmock -destination ../phase/testmock/detect_executor.go github.com/buildpacks/lifecycle/buildpack DetectExecutor
 type DetectExecutor interface {

buildpack/generate.go

@@ -34,7 +34,10 @@ type GenerateOutputs struct {
 	MetRequires []string
 }
 
-// GenerateExecutor TODO
+// GenerateExecutor executes a single image extension's `./bin/generate` binary,
+// providing inputs as defined in the Buildpack Interface Specification,
+// and processing outputs for the platform.
+// Pre-populated outputs for image extensions that are missing `./bin/generate` are processed here.
 //
 //go:generate mockgen -package testmock -destination ../phase/testmock/generate_executor.go github.com/buildpacks/lifecycle/buildpack GenerateExecutor
 type GenerateExecutor interface {

cmd/apis.go

@@ -24,37 +24,45 @@ var DeprecationMode = EnvOrDefault(EnvDeprecationMode, DefaultDeprecationMode)
 
 type BuildpackAPIVerifier struct{}
 
-func (v *BuildpackAPIVerifier) VerifyBuildpackAPI(kind, name, requested string, logger log.Logger) error {
-	return VerifyBuildpackAPI(kind, name, requested, logger)
+// VerifyBuildpackAPI given a Buildpack API version and relevant information for logging
+// will error if the requested version is unsupported,
+// and will log a warning, error, or do nothing if the requested version is deprecated,
+// depending on if the configured deprecation mode is "warn", "error", or "silent", respectively.
+func (v *BuildpackAPIVerifier) VerifyBuildpackAPI(kind, name, requestedVersion string, logger log.Logger) error {
+	return VerifyBuildpackAPI(kind, name, requestedVersion, logger)
 }
 
-func VerifyBuildpackAPI(kind, name, requested string, logger log.Logger) error {
-	requestedAPI, err := api.NewVersion(requested)
+// VerifyBuildpackAPI given a Buildpack API version and relevant information for logging
+// will error if the requested version is unsupported,
+// and will log a warning, error, or do nothing if the requested version is deprecated,
+// depending on if the configured deprecation mode is "warn", "error", or "silent", respectively.
+func VerifyBuildpackAPI(kind, name, requestedVersion string, logger log.Logger) error {
+	requested, err := api.NewVersion(requestedVersion)
 	if err != nil {
 		return FailErrCode(
 			nil,
 			CodeForIncompatibleBuildpackAPI,
-			fmt.Sprintf("parse buildpack API '%s' for %s '%s'", requestedAPI, strings.ToLower(kind), name),
+			fmt.Sprintf("parse buildpack API '%s' for %s '%s'", requested, strings.ToLower(kind), name),
 		)
 	}
-	if api.Buildpack.IsSupported(requestedAPI) {
-		if api.Buildpack.IsDeprecated(requestedAPI) {
+	if api.Buildpack.IsSupported(requested) {
+		if api.Buildpack.IsDeprecated(requested) {
 			switch DeprecationMode {
 			case ModeQuiet:
 				break
 			case ModeError:
-				logger.Errorf("%s '%s' requests deprecated API '%s'", kind, name, requested)
+				logger.Errorf("%s '%s' requests deprecated API '%s'", kind, name, requestedVersion)
 				logger.Errorf("Deprecated APIs are disabled by %s=%s", EnvDeprecationMode, ModeError)
-				return buildpackAPIError(kind, name, requested)
+				return buildpackAPIError(kind, name, requestedVersion)
 			case ModeWarn:
-				logger.Warnf("%s '%s' requests deprecated API '%s'", kind, name, requested)
+				logger.Warnf("%s '%s' requests deprecated API '%s'", kind, name, requestedVersion)
 			default:
-				logger.Warnf("%s '%s' requests deprecated API '%s'", kind, name, requested)
+				logger.Warnf("%s '%s' requests deprecated API '%s'", kind, name, requestedVersion)
 			}
 		}
 		return nil
 	}
-	return buildpackAPIError(kind, name, requested)
+	return buildpackAPIError(kind, name, requestedVersion)
 }
 
 func buildpackAPIError(moduleKind string, name string, requested string) error {
@@ -65,40 +73,44 @@ func buildpackAPIError(moduleKind string, name string, requested string) error {
 	)
 }
 
-func VerifyPlatformAPI(requested string, logger log.Logger) error {
-	if strings.TrimSpace(requested) == "" {
+// VerifyPlatformAPI given a Platform API version and relevant information for logging
+// will error if the requested version is unsupported,
+// and will log a warning, error, or do nothing if the requested version is deprecated,
+// depending on if the configured deprecation mode is "warn", "error", or "silent", respectively.
+func VerifyPlatformAPI(requestedVersion string, logger log.Logger) error {
+	if strings.TrimSpace(requestedVersion) == "" {
 		return FailErrCode(
 			nil,
 			CodeForIncompatiblePlatformAPI,
 			fmt.Sprintf("get platform API version; please set '%s' to specify the desired platform API version", EnvPlatformAPI),
 		)
 	}
-	requestedAPI, err := api.NewVersion(requested)
+	requested, err := api.NewVersion(requestedVersion)
 	if err != nil {
 		return FailErrCode(
 			nil,
 			CodeForIncompatiblePlatformAPI,
-			fmt.Sprintf("parse platform API '%s'", requested),
+			fmt.Sprintf("parse platform API '%s'", requestedVersion),
 		)
 	}
-	if api.Platform.IsSupported(requestedAPI) {
-		if api.Platform.IsDeprecated(requestedAPI) {
+	if api.Platform.IsSupported(requested) {
+		if api.Platform.IsDeprecated(requested) {
 			switch DeprecationMode {
 			case ModeQuiet:
 				break
 			case ModeError:
-				logger.Errorf("Platform requested deprecated API '%s'", requested)
+				logger.Errorf("Platform requested deprecated API '%s'", requestedVersion)
 				logger.Errorf("Deprecated APIs are disabled by %s=%s", EnvDeprecationMode, ModeError)
-				return platformAPIError(requested)
+				return platformAPIError(requestedVersion)
 			case ModeWarn:
-				logger.Warnf("Platform requested deprecated API '%s'", requested)
+				logger.Warnf("Platform requested deprecated API '%s'", requestedVersion)
 			default:
-				logger.Warnf("Platform requested deprecated API '%s'", requested)
+				logger.Warnf("Platform requested deprecated API '%s'", requestedVersion)
 			}
 		}
 		return nil
 	}
-	return platformAPIError(requested)
+	return platformAPIError(requestedVersion)
 }
 
 func platformAPIError(requested string) error {

image/handler.go

@@ -7,6 +7,11 @@ import (
 	"github.com/google/go-containerregistry/pkg/authn"
 )
 
+// Handler wraps initialization of an [imgutil] image.
+//
+// [imgutil]: github.com/buildpacks/imgutil
+//
+//go:generate mockgen -package testmock -destination ../phase/testmock/image_handler.go github.com/buildpacks/lifecycle/image Handler
 type Handler interface {
 	InitImage(imageRef string) (imgutil.Image, error)
 	Kind() string

internal/layer/metadata_restorer.go

@@ -14,7 +14,10 @@ import (
 	"github.com/buildpacks/lifecycle/platform/files"
 )
 
-// MetadataRestorer TODO
+// MetadataRestorer given a group of buildpacks and metadata from the previous image and cache,
+// will create `<layers>/<buildpack-id>/<layer>.toml` files containing `metadata` that the buildpack previously wrote.
+// Note that layer `types` information is not persisted, as the buildpack must opt in to layer re-use
+// by editing the provided `<layer>.toml` to configure the desired layer type.
 //
 //go:generate mockgen -package testmock -destination ../../phase/testmock/metadata_restorer.go github.com/buildpacks/lifecycle/internal/layer MetadataRestorer
 type MetadataRestorer interface {

internal/layer/sbom_restorer.go

@@ -20,7 +20,10 @@ import (
 	"github.com/buildpacks/lifecycle/log"
 )
 
-// SBOMRestorer TODO
+// SBOMRestorer handles the restoration of SBOM layer data.
+// Given a previous image or cache, it will extract the SBOM layer to the local filesystem.
+// Given a group of buildpacks and a `<layers>/sbom/<cache|launch>` directory,
+// it will copy the relevant SBOM files to `<layers>/<buildpack-id>/ so that they can be used in the current build.
 //
 //go:generate mockgen -package testmock -destination ../../phase/testmock/sbom_restorer.go github.com/buildpacks/lifecycle/internal/layer SBOMRestorer
 type SBOMRestorer interface {

phase/builder.go

@@ -25,7 +25,7 @@ type Platform interface {
 	API() *api.Version
 }
 
-// BuildEnv TODO
+// BuildEnv encapsulates modifications that the lifecycle can make to buildpacks' build environment.
 //
 //go:generate mockgen -package testmock -destination testmock/build_env.go github.com/buildpacks/lifecycle/phase BuildEnv
 type BuildEnv interface {

phase/detector.go

@@ -28,7 +28,10 @@ var (
 	ErrBuildpack       = errors.New("buildpack(s) failed with err")
 )
 
-// DetectResolver TODO
+// DetectResolver given a group of buildpacks (and optional image extensions)
+// processes the outputs of each `./bin/detect` to determine if the group is viable -
+// that is, whether all non-optional buildpacks passed detection and a valid Build Plan can be resolved
+// from each "requires" and "provides" expressed by each group element.
 //
 //go:generate mockgen -package testmock -destination testmock/detect_resolver.go github.com/buildpacks/lifecycle/phase DetectResolver
 type DetectResolver interface {

phase/exporter.go

@@ -47,7 +47,8 @@ type Exporter struct {
 	PlatformAPI  *api.Version
 }
 
-// LayerFactory TODO
+// LayerFactory given a directory on the local filesystem will return a `layers.Layer`
+// that can be used to construct an OCI image.
 //
 //go:generate mockgen -package testmock -destination testmock/layer_factory.go github.com/buildpacks/lifecycle/phase LayerFactory
 type LayerFactory interface {

phase/extender.go

@@ -39,7 +39,8 @@ type Extender struct {
 	Extensions        []buildpack.GroupElement // extensions are ordered from group.toml
 }
 
-// DockerfileApplier TODO
+// DockerfileApplier given a base image and a `build.Dockerfile` or `run.Dockerfile` will apply it to the base image
+// and return a new image, or an error if encountered.
 //
 //go:generate mockgen -package testmock -destination testmock/dockerfile_applier.go github.com/buildpacks/lifecycle/phase DockerfileApplier
 type DockerfileApplier interface {

phase/handlers.go

@@ -12,14 +12,16 @@ import (
 
 var Config = &DefaultConfigHandler{}
 
-// CacheHandler TODO
+// CacheHandler wraps initialization of a cache image or cache volume.
 //
 //go:generate mockgen -package testmock -destination testmock/cache_handler.go github.com/buildpacks/lifecycle/phase CacheHandler
 type CacheHandler interface {
 	InitCache(imageRef, dir string, deletionEnabled bool) (Cache, error)
 }
 
-// DirStore TODO
+// DirStore is a repository of buildpacks and/or image extensions.
+// Each element should be present on disk according to the format outlined in the Buildpack Interface Specification,
+// namely: `/cnb/<buildpacks|extensions>/<id>/<version>/<root directory>`.
 //
 //go:generate mockgen -package testmock -destination testmock/dir_store.go github.com/buildpacks/lifecycle/phase DirStore
 type DirStore interface {
@@ -28,17 +30,14 @@ type DirStore interface {
 	LookupExt(id, version string) (*buildpack.ExtDescriptor, error)
 }
 
-// TODO: figure out where this goes
-//go:generate mockgen -package testmock -destination testmock/image_handler.go github.com/buildpacks/lifecycle/image Handler
-
-// BuildpackAPIVerifier TODO
+// BuildpackAPIVerifier verifies a requested Buildpack API version.
 //
 //go:generate mockgen -package testmock -destination testmock/buildpack_api_verifier.go github.com/buildpacks/lifecycle/phase BuildpackAPIVerifier
 type BuildpackAPIVerifier interface {
-	VerifyBuildpackAPI(kind, name, requested string, logger log.Logger) error
+	VerifyBuildpackAPI(kind, name, requestedVersion string, logger log.Logger) error
 }
 
-// ConfigHandler TODO
+// ConfigHandler reads configuration files for the lifecycle.
 //
 //go:generate mockgen -package testmock -destination testmock/config_handler.go github.com/buildpacks/lifecycle/phase ConfigHandler
 type ConfigHandler interface {

phase/phase.go

@@ -1,2 +1,6 @@
-// Package phase TODO
+// Package phase handles logic internal to the CNB lifecycle,
+// and roughly corresponds to the actions denoted by "the lifecycle MUST" and "the lifecycle SHALL"
+// in the [Platform Interface Specification].
+//
+// [Platform Interface Specification]: https://github.com/buildpacks/spec/blob/main/platform.md
 package phase