Adding comments on Kanister Resource Types Fields in types.go (#1751)

* Adding comments on Kanister Resource Types

There were comments missing from kanister resource types fields in types.go which because of which the documentation was not coming out to be proper. So, added missing comments on types.go

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modification in the comments for types.go

Made some modifications in the comments under types.go by refering to https://docs.kanister.io/architecture.html#profiles

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modification on comment

Added 'Represents' prefix on comment

* Modification and addition of comments presnet in types.go

Added new comments and modified few existing comments for better understanding.

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modification and addition of comments in types.go

Added new comments and modified existing comments for better understanding.

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modifying and adding comments in types.go

Added new comments and modified few existing comments present in types.go for better understanding.

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modified existing comments in types.go

Modified few comments present in the types.go file so it would be easier to understand the fields.

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modification of comments in types.go

Modified few existing comments present in types.go file, for better understanding of the fields.

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modified Kind comment

Removed deprecated comment from kind field in types.go file.

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Modification in comments in types.go

Made modification on the comments in the types.go file

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>

* Update comments in types.go

modifying the grammar to make it better

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating Comments

Modified the comments in types.go to make it more understanding.

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

modifying the comment present for profile

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

updating comments

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

Modified the comment present on the Bucket

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

Modifying the comment present for Prefix

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

Modifying the comment present on Region

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

Modifying for Types comment

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Updating types.go

Modifying comments present on the KeyPair

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

modified comments present on the username

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

Modifying comments present on the hostname

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

modifying the comments present on Key field

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

Modifying the comment present on the Secret field

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

Modifying the comments present on Items

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

modifying comment present on the IDField

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

* Update pkg/apis/cr/v1alpha1/types.go

Modifying comment present on the field SecretField

Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>

Signed-off-by: Kartik-Garg <kartikgarg938@gmail.com>
Co-authored-by: Pavan Navarathna <6504783+pavannd1@users.noreply.github.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

pkg/apis/cr/v1alpha1/types.go

@@ -51,8 +51,12 @@ var _ runtime.Object = (*ActionSet)(nil)
 type ActionSet struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata"`
-	Spec              *ActionSetSpec   `json:"spec,omitempty"`
-	Status            *ActionSetStatus `json:"status,omitempty"`
+	// Spec defines the specification for the actionset.
+	// The specification includes a list of Actions to be performed. Each Action includes details
+	// about the referenced Blueprint and other objects used to perform the defined action.
+	Spec *ActionSetSpec `json:"spec,omitempty"`
+	// Status refers to the current status of the Kanister actions.
+	Status *ActionSetStatus `json:"status,omitempty"`
 }
 
 // ObjectReference refers to a kubernetes object.
@@ -76,6 +80,7 @@ type ObjectReference struct {
 
 // ActionSetSpec is the specification for the actionset.
 type ActionSetSpec struct {
+	// Actions represents a list of Actions that need to be performed by the actionset.
 	Actions []ActionSpec `json:"actions,omitempty"`
 }
 
@@ -109,9 +114,16 @@ type ActionSpec struct {
 
 // ActionSetStatus is the status for the actionset. This should only be updated by the controller.
 type ActionSetStatus struct {
-	State    State          `json:"state"`
-	Actions  []ActionStatus `json:"actions,omitempty"`
-	Error    Error          `json:"error,omitempty"`
+	// State represents the current state of the actionset.
+	// There are four possible values: "Pending", "Running", "Failed", and "Complete".
+	State State `json:"state"`
+	// Actions list represents the latest available observations of the current state of all the actions.
+	Actions []ActionStatus `json:"actions,omitempty"`
+	// Error contains the detailed error message of an actionset failure.
+	Error Error `json:"error,omitempty"`
+	// Progress provides information on the progress of a running actionset.
+	// This includes the percentage of completion of an actionset and the phase that is
+	// currently being executed.
 	Progress ActionProgress `json:"progress,omitempty"`
 }
 
@@ -158,21 +170,27 @@ const (
 	StateComplete State = "complete"
 )
 
+// Error represents an error that occurred when executing an actionset.
 type Error struct {
+	// Message is the actual error message that is displayed in case of errors.
 	Message string `json:"message"`
 }
 
 // Phase is subcomponent of an action.
 type Phase struct {
-	Name   string                 `json:"name"`
-	State  State                  `json:"state"`
+	// Name represents the name of the Blueprint phase.
+	Name string `json:"name"`
+	// State represents the current state of execution of the Blueprint phase.
+	State State `json:"state"`
+	// Output is the map of output artifacts produced by the Blueprint phase.
 	Output map[string]interface{} `json:"output,omitempty"`
 }
 
 // k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
 // Artifact tracks objects produced by an action.
 type Artifact struct {
+	// KeyValue represents key-value pair artifacts produced by the action.
 	KeyValue map[string]string `json:"keyValue,omitempty"`
 	// KopiaSnapshot captures the kopia snapshot information
 	// produced as a JSON string by kando command in phases of an action.
@@ -181,11 +199,12 @@ type Artifact struct {
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// ActionSetList is the definition of a list of ActionSets
+// ActionSetList is the definition of a list of actionsets.
 type ActionSetList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
-	Items           []*ActionSet `json:"items"`
+	// Items is the list of actionsets.
+	Items []*ActionSet `json:"items"`
 }
 
 var _ runtime.Object = (*Blueprint)(nil)
@@ -198,27 +217,43 @@ var _ runtime.Object = (*Blueprint)(nil)
 type Blueprint struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata"`
-	Actions           map[string]*BlueprintAction `json:"actions,omitempty"`
+	// Actions is the list of actions constructing the Blueprint.
+	Actions map[string]*BlueprintAction `json:"actions,omitempty"`
 }
 
 // BlueprintAction describes the set of phases that constitute an action.
 type BlueprintAction struct {
-	Name               string              `json:"name"`
-	Kind               string              `json:"kind"`
-	ConfigMapNames     []string            `json:"configMapNames,omitempty"`
-	SecretNames        []string            `json:"secretNames,omitempty"`
-	InputArtifactNames []string            `json:"inputArtifactNames,omitempty"`
-	OutputArtifacts    map[string]Artifact `json:"outputArtifacts,omitempty"`
-	Phases             []BlueprintPhase    `json:"phases,omitempty"`
-	DeferPhase         *BlueprintPhase     `json:"deferPhase,omitempty"`
+	// Name contains the name of the action.
+	Name string `json:"name"`
+	// Kind contains the resource on which this action has to be performed.
+	Kind string `json:"kind"`
+	// ConfigMapNames is used to specify the config map names that can be used later in the action phases.
+	ConfigMapNames []string `json:"configMapNames,omitempty"`
+	// List of Kubernetes secret names used in action phases.
+	SecretNames []string `json:"secretNames,omitempty"`
+	// InputArtifactNames is the list of Artifact names that were set from previous action and can be consumed in the current action.
+	InputArtifactNames []string `json:"inputArtifactNames,omitempty"`
+	// OutputArtifacts is the map of rendered artifacts produced by the BlueprintAction.
+	OutputArtifacts map[string]Artifact `json:"outputArtifacts,omitempty"`
+	// Phases is the list of BlueprintPhases which are invoked in order when executing this action.
+	Phases []BlueprintPhase `json:"phases,omitempty"`
+	// DeferPhase is invoked after the execution of Phases that are defined for an action.
+	// A DeferPhase is executed regardless of the statuses of the other phases of the action.
+	// A DeferPhase can be used for cleanup operations at the end of an action.
+	DeferPhase *BlueprintPhase `json:"deferPhase,omitempty"`
 }
 
 // BlueprintPhase is a an individual unit of execution.
 type BlueprintPhase struct {
-	Func       string                     `json:"func"`
-	Name       string                     `json:"name"`
+	// Func is the name of a registered Kanister function.
+	Func string `json:"func"`
+	// Name contains name of the phase.
+	Name string `json:"name"`
+	// ObjectRefs represents a map of references to the Kubernetes objects that
+	// can later be used in the `Args` of the function.
 	ObjectRefs map[string]ObjectReference `json:"objects,omitempty"`
-	Args       map[string]interface{}     `json:"args"`
+	// Args represents a map of named arguments that the controller will pass to the Kanister function.
+	Args map[string]interface{} `json:"args"`
 }
 
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
@@ -227,20 +262,27 @@ type BlueprintPhase struct {
 type BlueprintList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
-	Items           []*Blueprint `json:"items"`
+	// Items is the list of Blueprints.
+	Items []*Blueprint `json:"items"`
 }
 
 // +genclient
 // +genclient:noStatus
 // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
 
-// Profile
+// Profile captures information about a storage location for backup artifacts and
+// corresponding credentials, that will be made available to a Blueprint phase.
 type Profile struct {
 	metav1.TypeMeta   `json:",inline"`
 	metav1.ObjectMeta `json:"metadata"`
-	Location          Location   `json:"location"`
-	Credential        Credential `json:"credential"`
-	SkipSSLVerify     bool       `json:"skipSSLVerify"`
+	// Location provides the information about the object storage that is going to be used by Kanister to upload the backup objects.
+	Location Location `json:"location"`
+	// Credential represents the credentials associated with the Location.
+	Credential Credential `json:"credential"`
+	// SkipSSLVerify is a boolean that specifies whether skipping SSL verification
+	// is allowed when operating with the Location.
+	// If omitted from the CR definition, it defaults to false
+	SkipSSLVerify bool `json:"skipSSLVerify"`
 }
 
 // LocationType
@@ -255,11 +297,19 @@ const (
 
 // Location
 type Location struct {
-	Type     LocationType `json:"type"`
-	Bucket   string       `json:"bucket"`
-	Endpoint string       `json:"endpoint"`
-	Prefix   string       `json:"prefix"`
-	Region   string       `json:"region"`
+	// Type specifies the kind of object storage that would be used to upload the
+	// backup objects. Currently supported values are: "GCS", "S3Compliant",
+	// and "Azure".
+	Type LocationType `json:"type"`
+	// Bucket represents the bucket on the object storage where the backup is uploaded.
+	Bucket string `json:"bucket"`
+	// Endpoint specifies the endpoint where the object storage is accessible at.
+	Endpoint string `json:"endpoint"`
+	// Prefix is the string that would be prepended to the object path in the
+	// bucket where the backup objects are uploaded.
+	Prefix string `json:"prefix"`
+	// Region represents the region of the bucket specified above.
+	Region string `json:"region"`
 }
 
 // CredentialType
@@ -273,31 +323,46 @@ const (
 
 // Credential
 type Credential struct {
-	Type              CredentialType     `json:"type"`
-	KeyPair           *KeyPair           `json:"keyPair,omitempty"`
-	Secret            *ObjectReference   `json:"secret,omitempty"`
+	// Type represents the information about how the credentials are provided for the respective object storage.
+	Type CredentialType `json:"type"`
+	// KeyPair represents the key-value map used for the Credential of Type KeyPair.
+	KeyPair *KeyPair `json:"keyPair,omitempty"`
+	// Secret represents the Kubernetes Secret Object used for the Credential of Type Secret.
+	Secret *ObjectReference `json:"secret,omitempty"`
+	// KopiaServerSecret represents the secret being used by Credential of Type Kopia.
 	KopiaServerSecret *KopiaServerSecret `json:"kopiaServerSecret,omitempty"`
 }
 
 // KeyPair
 type KeyPair struct {
-	IDField     string          `json:"idField"`
-	SecretField string          `json:"secretField"`
-	Secret      ObjectReference `json:"secret"`
+	// IDField specifies the corresponding key in the secret where the AWS Key ID value is stored.
+	IDField string `json:"idField"`
+	// SecretField specifies the corresponding key in the secret where the AWS Secret Key value is stored.
+	SecretField string `json:"secretField"`
+	// Secret represents a Kubernetes Secret object storing the KeyPair credentials.
+	Secret ObjectReference `json:"secret"`
 }
 
 // KopiaServerSecret contains credentials to connect to Kopia server
 type KopiaServerSecret struct {
-	Username       string                `json:"username,omitempty"`
-	Hostname       string                `json:"hostname,omitempty"`
+	// Username represents the username used to connect to the Kopia Server.
+	Username string `json:"username,omitempty"`
+	// Hostname represents the hostname used to connect to the Kopia Server.
+	Hostname string `json:"hostname,omitempty"`
+	// UserPassphrase is the user password used to connect to the Kopia Server.
 	UserPassphrase *KopiaServerSecretRef `json:"userPassphrase,omitempty"`
-	TLSCert        *KopiaServerSecretRef `json:"tlsCert,omitempty"`
-	ConnectOptions map[string]int        `json:"connectOptions,omitempty"`
+	// TLSCert is the certificate used to connect to the Kopia Server.
+	TLSCert *KopiaServerSecretRef `json:"tlsCert,omitempty"`
+	// ConnectOptions represents a map of options which can be used to connect to the Kopia Server.
+	ConnectOptions map[string]int `json:"connectOptions,omitempty"`
 }
 
 // KopiaServerSecretRef refers to K8s secrets containing Kopia creds
 type KopiaServerSecretRef struct {
-	Key    string           `json:"key"`
+	// Key represents the corresponding key in the secret where the required
+	// credential or certificate value is stored.
+	Key string `json:"key"`
+	// Secret is the K8s secret object where the creds related to the Kopia Server are stored.
 	Secret *ObjectReference `json:"secret"`
 }
 
@@ -307,5 +372,6 @@ type KopiaServerSecretRef struct {
 type ProfileList struct {
 	metav1.TypeMeta `json:",inline"`
 	metav1.ListMeta `json:"metadata"`
-	Items           []*Profile `json:"items"`
+	// Items represents a list of Profiles.
+	Items []*Profile `json:"items"`
 }