Add and fix various docstrings and comments ✍️

While working on tektoncd#1417, which we decided in the end not to merge, I made
a bunch of updates to docstrings and comments which are now in this
commit:
- Adding more detail to some docstrings
- Adding missing docstrings
- Updating docstrings that were sometimes wrong (e.g. a function name
  had changed)
- Removing some comments in the Conditions logic that were no longer
  accurate
- Added comments in some sections of code that took me a while to
  understand to hopefully make it faster next time :)

pkg/apis/pipeline/v1alpha1/artifact_pvc.go

@@ -28,26 +28,25 @@ var (
  pvcDir = "/pvc"
 )
 
-// ArtifactPVC represents the pvc created by the pipelinerun
-// for artifacts temporary storage
+// ArtifactPVC represents the pvc created by the pipelinerun for artifacts temporary storage.
 type ArtifactPVC struct {
  Name string
  PersistentVolumeClaim *corev1.PersistentVolumeClaim
 
  BashNoopImage string
 }
 
-// GetType returns the type of the artifact storage
+// GetType returns the type of the artifact storage.
 func (p *ArtifactPVC) GetType() string {
  return ArtifactStoragePVCType
 }
 
-// StorageBasePath returns the path to be used to store artifacts in a pipelinerun temporary storage
+// StorageBasePath returns the path to be used to store artifacts in a pipelinerun temporary storage.
 func (p *ArtifactPVC) StorageBasePath(pr *PipelineRun) string {
  return pvcDir
 }
 
-// GetCopyFromStorageToSteps returns a container used to download artifacts from temporary storage
+// GetCopyFromStorageToSteps returns a container used to download artifacts from temporary storage.
 func (p *ArtifactPVC) GetCopyFromStorageToSteps(name, sourcePath, destinationPath string) []Step {
  return []Step{{Container: corev1.Container{
  Name: names.SimpleNameGenerator.RestrictLengthWithRandomSuffix(fmt.Sprintf("source-copy-%s", name)),
@@ -57,7 +56,7 @@ func (p *ArtifactPVC) GetCopyFromStorageToSteps(name, sourcePath, destinationPat
  }}}
 }
 
-// GetCopyToStorageFromSteps returns a container used to upload artifacts for temporary storage
+// GetCopyToStorageFromSteps returns a container used to upload artifacts for temporary storage.
 func (p *ArtifactPVC) GetCopyToStorageFromSteps(name, sourcePath, destinationPath string) []Step {
  return []Step{{Container: corev1.Container{
  Name: names.SimpleNameGenerator.RestrictLengthWithRandomSuffix(fmt.Sprintf("source-mkdir-%s", name)),
@@ -78,15 +77,16 @@ func (p *ArtifactPVC) GetCopyToStorageFromSteps(name, sourcePath, destinationPat
  }}}
 }
 
-// GetPvcMount returns a mounting of the volume with the mount path /pvc
+// GetPvcMount returns a mounting of the volume with the mount path /pvc.
 func GetPvcMount(name string) corev1.VolumeMount {
  return corev1.VolumeMount{
  Name: name, // taskrun pvc name
  MountPath: pvcDir, // nothing should be mounted here
  }
 }
 
-// CreateDirStep returns a container step to create a dir
+// CreateDirStep returns a container step to create a dir at destinationPath. The name
+// of the step will include name.
 func CreateDirStep(bashNoopImage string, name, destinationPath string) Step {
  return Step{Container: corev1.Container{
  Name: names.SimpleNameGenerator.RestrictLengthWithRandomSuffix(fmt.Sprintf("create-dir-%s", strings.ToLower(name))),

pkg/apis/pipeline/v1alpha1/build_gcs_resource.go

@@ -59,7 +59,6 @@ var validArtifactTypes = []GCSArtifactType{
 // BuildGCSResource describes a resource in the form of an archive,
 // or a source manifest describing files to fetch.
 // BuildGCSResource does incremental uploads for files in directory.
-
 type BuildGCSResource struct {
  Name string
  Type PipelineResourceType
@@ -70,7 +69,7 @@ type BuildGCSResource struct {
  BuildGCSFetcherImage string `json:"-"`
 }
 
-// creates a new BuildGCS resource to pass to a Task
+// NewBuildGCSResource creates a new BuildGCS resource to pass to a Task.
 func NewBuildGCSResource(images pipeline.Images, r *PipelineResource) (*BuildGCSResource, error) {
  if r.Spec.Type != PipelineResourceTypeStorage {
  return nil, xerrors.Errorf("BuildGCSResource: Cannot create a BuildGCS resource from a %s Pipeline Resource", r.Spec.Type)

pkg/apis/pipeline/v1alpha1/resource_types.go

@@ -54,10 +54,18 @@ var AllResourceTypes = []PipelineResourceType{PipelineResourceTypeGit, PipelineR
 
 // PipelineResourceInterface interface to be implemented by different PipelineResource types
 type PipelineResourceInterface interface {
+ // GetName returns the name of this PipelineResource instance.
  GetName() string
+ // GetType returns the type of this PipelineResource (often a super type, e.g. in the case of storage).
  GetType() PipelineResourceType
+ // Replacements returns all the attributes that this PipelineResource has that
+ // can be used for variable replacement.
  Replacements() map[string]string
+ // GetOutputTaskModifier returns the TaskModifier instance that should be used on a Task
+ // in order to add this kind of resource when it is being used as an output.
  GetOutputTaskModifier(ts *TaskSpec, path string) (TaskModifier, error)
+ // GetInputTaskModifier returns the TaskModifier instance that should be used on a Task
+ // in order to add this kind of resource when it is being used as an input.
  GetInputTaskModifier(ts *TaskSpec, path string) (TaskModifier, error)
 }
 
@@ -201,7 +209,9 @@ type ResourceDeclaration struct {
  TargetPath string `json:"targetPath,omitempty"`
 }
 
-// ResourceFromType returns a PipelineResourceInterface from a PipelineResource's type.
+// ResourceFromType returns an instance of the correct PipelineResource object type which can be
+// used to add input and ouput containers as well as volumes to a TaskRun's pod in order to realize
+// a PipelineResource in a pod.
 func ResourceFromType(r *PipelineResource, images pipeline.Images) (PipelineResourceInterface, error) {
  switch r.Spec.Type {
  case PipelineResourceTypeGit:

pkg/apis/pipeline/v1alpha1/storage_resource.go

@@ -28,17 +28,24 @@ import (
 type PipelineResourceStorageType string
 
 const (
- // PipelineResourceTypeGCS indicates that resource source is a GCS blob/directory.
- PipelineResourceTypeGCS PipelineResourceType = "gcs"
+ // PipelineResourceTypeGCS is the subtype for the GCSResources, which is backed by a GCS blob/directory.
+ PipelineResourceTypeGCS PipelineResourceType = "gcs"
+
+ // PipelineResourceTypeBuildGCS is the subtype for the BuildGCSResources, which is simialr to the GCSResource but
+ // with additional funcitonality that was added to be compatible with knative build.
  PipelineResourceTypeBuildGCS PipelineResourceType = "build-gcs"
 )
 
-// PipelineResourceInterface interface to be implemented by different PipelineResource types
+// PipelineStorageResourceInterface is the interface for subtypes of the storage type.
+// It adds a function to the PipelineResourceInterface for retrieving secrets that are usually
+// needed for storage PipelineResources.
 type PipelineStorageResourceInterface interface {
  PipelineResourceInterface
  GetSecretParams() []SecretParam
 }
 
+// NewStorageResource returns an instance of the requested storage subtype, which can be used
+// to add input and output steps and volumes to an executing pod.
 func NewStorageResource(images pipeline.Images, r *PipelineResource) (PipelineStorageResourceInterface, error) {
  if r.Spec.Type != PipelineResourceTypeStorage {
  return nil, xerrors.Errorf("StoreResource: Cannot create a storage resource from a %s Pipeline Resource", r.Spec.Type)

pkg/reconciler/pipelinerun/resources/conditionresolution.go

@@ -110,9 +110,7 @@ func (rcc *ResolvedConditionCheck) ConditionToTaskSpec() (*v1alpha1.TaskSpec, er
  })
  }
 
- // convert param strings of type $(params.x) to $(inputs.params.x)
  convertParamTemplates(&t.Steps[0], rcc.Condition.Spec.Params)
- // convert resource strings of type $(resources.name.key) to $(inputs.resources.name.key)
  err := ApplyResourceSubstitution(&t.Steps[0], rcc.ResolvedResources, rcc.Condition.Spec.Resources, rcc.images)
 
  if err != nil {
@@ -122,7 +120,7 @@ func (rcc *ResolvedConditionCheck) ConditionToTaskSpec() (*v1alpha1.TaskSpec, er
  return t, nil
 }
 
-// Replaces all instances of $(params.x) in the container to $(inputs.params.x) for each param name
+// convertParamTemplates replaces all instances of $(params.x) in the container to $(inputs.params.x) for each param name.
 func convertParamTemplates(step *v1alpha1.Step, params []v1alpha1.ParamSpec) {
  replacements := make(map[string]string)
  for _, p := range params {
@@ -133,8 +131,7 @@ func convertParamTemplates(step *v1alpha1.Step, params []v1alpha1.ParamSpec) {
  v1alpha1.ApplyStepReplacements(step, replacements, map[string][]string{})
 }
 
-// ApplyResources applies the substitution from values in resources which are referenced
-// in spec as subitems of the replacementStr.
+// ApplyResourceSubstitution applies resource attribute variable substitution.
 func ApplyResourceSubstitution(step *v1alpha1.Step, resolvedResources map[string]*v1alpha1.PipelineResource, conditionResources []v1alpha1.ResourceDeclaration, images pipeline.Images) error {
  replacements := make(map[string]string)
  for _, cr := range conditionResources {
@@ -153,7 +150,7 @@ func ApplyResourceSubstitution(step *v1alpha1.Step, resolvedResources map[string
  return nil
 }
 
-// NewConditionCheck status creates a ConditionCheckStatus from a ConditionCheck
+// NewConditionCheckStatus creates a ConditionCheckStatus from a ConditionCheck
 func (rcc *ResolvedConditionCheck) NewConditionCheckStatus() *v1alpha1.ConditionCheckStatus {
  var checkStep corev1.ContainerState
  trs := rcc.ConditionCheck.Status

pkg/reconciler/pipelinerun/resources/input_output_steps.go

@@ -22,7 +22,7 @@ import (
  "github.com/tektoncd/pipeline/pkg/apis/pipeline/v1alpha1"
 )
 
-// GetOutputSteps will add the correct `path` to the input resources for pt
+// GetOutputSteps will add the correct `path` to the output resources for pt
 func GetOutputSteps(outputs map[string]*v1alpha1.PipelineResource, taskName, storageBasePath string) []v1alpha1.TaskResourceBinding {
  var taskOutputResources []v1alpha1.TaskResourceBinding
 
@@ -78,6 +78,8 @@ func GetInputSteps(inputs map[string]*v1alpha1.PipelineResource, pt *v1alpha1.Pi
  }
  }
 
+ // Determine if the value is meant to come `from` a previous Task - if so, add the path to the pvc
+ // that contains the data as the `path` the resulting TaskRun should get the data from.
  var stepSourceNames []string
  if pt.Resources != nil {
  for _, pipelineTaskInput := range pt.Resources.Inputs {

pkg/reconciler/taskrun/resources/output_resource.go

@@ -110,6 +110,7 @@ func AddOutputResources(
  }
  v1alpha1.ApplyTaskModifier(taskSpec, modifier)
 
+ // Attach the PVC that will be used for `from` copying.
  if as.GetType() == v1alpha1.ArtifactStoragePVCType {
  if pvcName == "" {
  return taskSpec, nil