Add type-level godoc for various API types

pkg/apis/pipeline/v1alpha1/cluster_task_types.go

@@ -48,7 +48,9 @@ var _ apis.Defaultable = (*ClusterTask)(nil)
 // +genclient:nonNamespaced
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// ClusterTask is a Task with a cluster scope
+// ClusterTask is a Task with a cluster scope. ClusterTasks are used to
+// represent Tasks that should be publicly addressable from any namespace in the
+// cluster.
 type ClusterTask struct {
 	metav1.TypeMeta `json:",inline"`
 	// +optional

pkg/apis/pipeline/v1alpha1/pipelinerun_types.go

@@ -158,7 +158,12 @@ func (pr *PipelineRunStatus) SetCondition(newCond *apis.Condition) {
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// PipelineRun is the Schema for the pipelineruns API
+// PipelineRun represents a single execution of a Pipeline. PipelineRuns are how
+// the graph of Tasks declared in a Pipeline are executed; they specify inputs
+// to Pipelines such as parameter values and capture operational aspects of the
+// Tasks execution such as service account and tolerations. Creating a
+// PipelineRun creates TaskRuns for Tasks in the referenced Pipeline.
+//
 // +k8s:openapi-gen=true
 type PipelineRun struct {
 	metav1.TypeMeta `json:",inline"`

pkg/apis/pipeline/v1alpha1/resource_types.go

@@ -102,7 +102,9 @@ type TaskResource struct {
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// PipelineResource is the Schema for the pipelineResources API
+// PipelineResource describes a resource that is an input to or output from a
+// Task.
+//
 // +k8s:openapi-gen=true
 type PipelineResource struct {
 	metav1.TypeMeta `json:",inline"`

pkg/apis/pipeline/v1alpha1/task_types.go

@@ -63,7 +63,11 @@ var _ apis.Defaultable = (*Task)(nil)
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// Task is the Schema for the tasks API
+// Task represents a collection of sequential steps that are run as part of a
+// Pipeline using a set of inputs and producing a set of outputs. Tasks execute
+// when TaskRuns are created that provide the input parameters and resources and
+// output resources the Task requires.
+//
 // +k8s:openapi-gen=true
 type Task struct {
 	metav1.TypeMeta `json:",inline"`

pkg/apis/pipeline/v1alpha1/taskrun_types.go

@@ -156,7 +156,10 @@ type StepState struct {
 // +genclient
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// TaskRun is the Schema for the taskruns API
+// TaskRun represents a single execution of a Task. TaskRuns are how the steps
+// specified in a Task are executed; they specify the parameters and resources
+// used to run the steps in a Task.
+//
 // +k8s:openapi-gen=true
 type TaskRun struct {
 	metav1.TypeMeta `json:",inline"`