Update comments on some API objects

Avoid generically referring to "the container" where it can be ambiguous
that we're actually talking about the environment we set up for running
a command for a RUN instruction or Run() call.

Signed-off-by: Nalin Dahyabhai <nalin@redhat.com>

buildah.go

@@ -91,7 +91,7 @@ type Builder struct {
 	// Logger is the logrus logger to write log messages with
 	Logger *logrus.Logger `json:"-"`
 
-	// Args define variables that users can pass at build-time to the builder
+	// Args define variables that users can pass at build-time to the builder.
 	Args map[string]string
 	// Type is used to help identify a build container's metadata.  It
 	// should not be modified.
@@ -118,7 +118,7 @@ type Builder struct {
 	// MountPoint is the last location where the container's root
 	// filesystem was mounted.  It should not be modified.
 	MountPoint string `json:"mountpoint,omitempty"`
-	// ProcessLabel is the SELinux process label associated with the container
+	// ProcessLabel is the SELinux process label to use during subsequent Run() calls.
 	ProcessLabel string `json:"process-label,omitempty"`
 	// MountLabel is the SELinux mount label associated with the container
 	MountLabel string `json:"mount-label,omitempty"`
@@ -139,7 +139,7 @@ type Builder struct {
 
 	// Isolation controls how we handle "RUN" statements and the Run() method.
 	Isolation define.Isolation
-	// NamespaceOptions controls how we set up the namespaces for processes that we run in the container.
+	// NamespaceOptions controls how we set up the namespaces for processes that we Run().
 	NamespaceOptions define.NamespaceOptions
 	// ConfigureNetwork controls whether or not network interfaces and
 	// routing are configured for a new network namespace (i.e., when not
@@ -157,11 +157,11 @@ type Builder struct {
 	// NetworkInterface is the libnetwork network interface used to setup CNI or netavark networks.
 	NetworkInterface nettypes.ContainerNetwork `json:"-"`
 
-	// GroupAdd is a list of groups to add to the primary process within
-	// the container. 'keep-groups' allows container processes to use
-	// supplementary groups.
+	// GroupAdd is a list of groups to add to the primary process when Run() is
+	// called. The magic 'keep-groups' value indicates that the process should
+	// be allowed to inherit the current set of supplementary groups.
 	GroupAdd []string
-	// ID mapping options to use when running processes in the container with non-host user namespaces.
+	// ID mapping options to use when running processes with non-host user namespaces.
 	IDMappingOptions define.IDMappingOptions
 	// Capabilities is a list of capabilities to use when running commands in the container.
 	Capabilities []string
@@ -177,13 +177,14 @@ type Builder struct {
 	CommonBuildOpts     *define.CommonBuildOptions
 	// TopLayer is the top layer of the image
 	TopLayer string
-	// Format for the build Image
+	// Format to use for a container image we eventually commit, when we do.
 	Format string
-	// TempVolumes are temporary mount points created during container runs
+	// TempVolumes are temporary mount points created during Run() calls.
 	TempVolumes map[string]bool
-	// ContentDigester counts the digest of all Add()ed content
+	// ContentDigester counts the digest of all Add()ed content since it was
+	// last restarted.
 	ContentDigester CompositeDigester
-	// Devices are the additional devices to add to the containers
+	// Devices are parsed additional devices to provide to Run() calls.
 	Devices define.ContainerDevices
 }
 
@@ -328,12 +329,12 @@ type BuilderOptions struct {
 	// ID mapping options to use if we're setting up our own user namespace.
 	IDMappingOptions *define.IDMappingOptions
 	// Capabilities is a list of capabilities to use when
-	// running commands in the container.
+	// running commands for Run().
 	Capabilities    []string
 	CommonBuildOpts *define.CommonBuildOptions
-	// Format for the container image
+	// Format to use for a container image we eventually commit, when we do.
 	Format string
-	// Devices are the additional devices to add to the containers
+	// Devices are additional parsed devices to provide for Run() calls.
 	Devices define.ContainerDevices
 	// DefaultEnv is deprecated and ignored.
 	DefaultEnv []string
@@ -345,9 +346,9 @@ type BuilderOptions struct {
 	// OciDecryptConfig contains the config that can be used to decrypt an image if it is
 	// encrypted if non-nil. If nil, it does not attempt to decrypt an image.
 	OciDecryptConfig *encconfig.DecryptConfig
-	// ProcessLabel is the SELinux process label associated with the container
+	// ProcessLabel is the SELinux process label associated with commands we Run()
 	ProcessLabel string
-	// MountLabel is the SELinux mount label associated with the container
+	// MountLabel is the SELinux mount label associated with the working container
 	MountLabel string
 	// PreserveBaseImageAnns indicates that we should preserve base
 	// image information (Annotations) that are present in our base image,

define/build.go

@@ -59,7 +59,7 @@ type CommonBuildOptions struct {
 	DNSServers []string
 	// DNSOptions is the list of DNS
 	DNSOptions []string
-	// LabelOpts is the a slice of fields of an SELinux context, given in "field:pair" format, or "disable".
+	// LabelOpts is a slice of the fields of an SELinux context, given in "field:pair" format, or "disable".
 	// Recognized field names are "role", "type", and "level".
 	LabelOpts []string
 	// MemorySwap limits the amount of memory and swap together.
@@ -140,7 +140,8 @@ type BuildOptions struct {
 	Runtime string
 	// RuntimeArgs adds global arguments for the runtime.
 	RuntimeArgs []string
-	// TransientMounts is a list of mounts that won't be kept in the image.
+	// TransientMounts is a list of unparsed mounts that will be provided to
+	// RUN instructions.
 	TransientMounts []string
 	// CacheFrom specifies any remote repository which can be treated as
 	// potential cache source.
@@ -242,22 +243,24 @@ type BuildOptions struct {
 	CommonBuildOpts *CommonBuildOptions
 	// CPPFlags are additional arguments to pass to the C Preprocessor (cpp).
 	CPPFlags []string
-	// DefaultMountsFilePath is the file path holding the mounts to be mounted in "host-path:container-path" format
+	// DefaultMountsFilePath is the file path holding the mounts to be mounted for RUN
+	// instructions in "host-path:container-path" format
 	DefaultMountsFilePath string
 	// IIDFile tells the builder to write the image ID to the specified file
 	IIDFile string
-	// Squash tells the builder to produce an image with a single layer
-	// instead of with possibly more than one layer.
+	// Squash tells the builder to produce an image with a single layer instead of with
+	// possibly more than one layer, by only committing a new layer after processing the
+	// final instruction.
 	Squash bool
-	// Labels metadata for an image
+	// Labels to set in a committed image.
 	Labels []string
 	// LayerLabels metadata for an intermediate image
 	LayerLabels []string
-	// Annotation metadata for an image
+	// Annotations to set in a committed image, in OCI format.
 	Annotations []string
-	// OnBuild commands to be run by images based on this image
+	// OnBuild commands to be run by builds that use the image we'll commit as a base image.
 	OnBuild []string
-	// Layers tells the builder to create a cache of images for each step in the Dockerfile
+	// Layers tells the builder to commit an image for each step in the Dockerfile.
 	Layers bool
 	// NoCache tells the builder to build the image from scratch without checking for a cache.
 	// It creates a new set of cached images for the build.
@@ -272,7 +275,7 @@ type BuildOptions struct {
 	BlobDirectory string
 	// Target the targeted FROM in the Dockerfile to build.
 	Target string
-	// Devices are the additional devices to add to the containers.
+	// Devices are unparsed devices to provide to RUN instructions.
 	Devices []string
 	// SignBy is the fingerprint of a GPG key to use for signing images.
 	SignBy string
@@ -298,18 +301,18 @@ type BuildOptions struct {
 	JobSemaphore *semaphore.Weighted
 	// LogRusage logs resource usage for each step.
 	LogRusage bool
-	// File to which the Rusage logs will be saved to instead of stdout
+	// File to which the Rusage logs will be saved to instead of stdout.
 	RusageLogFile string
 	// Excludes is a list of excludes to be used instead of the .dockerignore file.
 	Excludes []string
 	// IgnoreFile is a name of the .containerignore file
 	IgnoreFile string
 	// From is the image name to use to replace the value specified in the first
-	// FROM instruction in the Containerfile
+	// FROM instruction in the Containerfile.
 	From string
-	// GroupAdd is a list of groups to add to the primary process within
-	// the container. 'keep-groups' allows container processes to use
-	// supplementary groups.
+	// GroupAdd is a list of groups to add to the primary process when handling RUN
+	// instructions. The magic 'keep-groups' value indicates that the process should
+	// be allowed to inherit the current set of supplementary groups.
 	GroupAdd []string
 	// Platforms is the list of parsed OS/Arch/Variant triples that we want
 	// to build the image for.  If this slice has items in it, the OS and

run.go

@@ -147,14 +147,13 @@ type RunOptions struct {
 	// after processing the AddCapabilities set.  If a capability appears in both
 	// lists, it will be dropped.
 	DropCapabilities []string
-	// Devices are the additional devices to add to the containers
+	// Devices are parsed additional devices to add
 	Devices define.ContainerDevices
-	// Secrets are the available secrets to use in a RUN
+	// Secrets are the available secrets to use
 	Secrets map[string]define.Secret
-	// SSHSources is the available ssh agents to use in a RUN
+	// SSHSources is the available ssh agents to use
 	SSHSources map[string]*sshagent.Source `json:"-"`
-	// RunMounts are mounts for this run. RunMounts for this run
-	// will not show up in subsequent runs.
+	// RunMounts are unparsed mounts to be added for this run
 	RunMounts []string
 	// Map of stages and container mountpoint if any from stage executor
 	StageMountPoints map[string]internal.StageMountDetails