Merge pull request #4916 from camilamacedo86/cronjob-tutorials-docs-fixes

📖 Update Cronjob Tutorials API spec descriptions to better adopt  k8s API convetions

Author: k8s-ci-robot

docs/book/src/cronjob-tutorial/testdata/project/api/v1/cronjob_types.go

@@ -64,46 +64,43 @@ import (
 
 // CronJobSpec defines the desired state of CronJob
 type CronJobSpec struct {
+	// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
 	// +kubebuilder:validation:MinLength=0
-
-	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// +required
 	Schedule string `json:"schedule"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// Optional deadline in seconds for starting the job if it misses scheduled
+	// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
 	// time for any reason.  Missed jobs executions will be counted as failed ones.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
 
-	// Specifies how to treat concurrent executions of a Job.
+	// concurrencyPolicy specifies how to treat concurrent executions of a Job.
 	// Valid values are:
 	// - "Allow" (default): allows CronJobs to run concurrently;
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
-	// This flag tells the controller to suspend subsequent executions, it does
+	// suspend tells the controller to suspend subsequent executions, it does
 	// not apply to already started executions.  Defaults to false.
 	// +optional
 	Suspend *bool `json:"suspend,omitempty"`
 
-	// Specifies the job that will be created when executing a CronJob.
+	// jobTemplate defines the job that will be created when executing a CronJob.
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// The number of successful finished jobs to retain.
+	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
-	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
-
 	// +kubebuilder:validation:Minimum=0
+	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
 
-	// The number of failed finished jobs to retain.
+	// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
 }
 
@@ -147,11 +144,11 @@ type CronJobStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	// A list of pointers to currently running jobs.
+	// active defines a list of pointers to currently running jobs.
 	// +optional
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
-	// Information when was the last time the job was successfully scheduled.
+	// lastScheduleTime defines when was the last time the job was successfully scheduled.
 	// +optional
 	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
 }

docs/book/src/multiversion-tutorial/testdata/project/api/v1/cronjob_types.go

@@ -36,46 +36,43 @@ import (
 
 // CronJobSpec defines the desired state of CronJob
 type CronJobSpec struct {
+	// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
 	// +kubebuilder:validation:MinLength=0
-
-	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// +required
 	Schedule string `json:"schedule"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// Optional deadline in seconds for starting the job if it misses scheduled
+	// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
 	// time for any reason.  Missed jobs executions will be counted as failed ones.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
 
-	// Specifies how to treat concurrent executions of a Job.
+	// concurrencyPolicy specifies how to treat concurrent executions of a Job.
 	// Valid values are:
 	// - "Allow" (default): allows CronJobs to run concurrently;
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
-	// This flag tells the controller to suspend subsequent executions, it does
+	// suspend tells the controller to suspend subsequent executions, it does
 	// not apply to already started executions.  Defaults to false.
 	// +optional
 	Suspend *bool `json:"suspend,omitempty"`
 
-	// Specifies the job that will be created when executing a CronJob.
+	// jobTemplate defines the job that will be created when executing a CronJob.
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// The number of successful finished jobs to retain.
+	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
-	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
-
 	// +kubebuilder:validation:Minimum=0
+	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
 
-	// The number of failed finished jobs to retain.
+	// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
 }
 
@@ -103,11 +100,11 @@ type CronJobStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	// A list of pointers to currently running jobs.
+	// active defines a list of pointers to currently running jobs.
 	// +optional
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
-	// Information when was the last time the job was successfully scheduled.
+	// lastScheduleTime defines when was the last time the job was successfully scheduled.
 	// +optional
 	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
 }

docs/book/src/multiversion-tutorial/testdata/project/api/v2/cronjob_types.go

@@ -47,41 +47,38 @@ type CronJobSpec struct {
 	/*
 	 */
 
-	// +kubebuilder:validation:Minimum=0
-
-	// Optional deadline in seconds for starting the job if it misses scheduled
+	// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
 	// time for any reason.  Missed jobs executions will be counted as failed ones.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`
 
-	// Specifies how to treat concurrent executions of a Job.
+	// concurrencyPolicy defines how to treat concurrent executions of a Job.
 	// Valid values are:
 	// - "Allow" (default): allows CronJobs to run concurrently;
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
 	ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`
 
-	// This flag tells the controller to suspend subsequent executions, it does
+	// suspend tells the controller to suspend subsequent executions, it does
 	// not apply to already started executions.  Defaults to false.
 	// +optional
 	Suspend *bool `json:"suspend,omitempty"`
 
-	// Specifies the job that will be created when executing a CronJob.
+	// jobTemplate defines the job that will be created when executing a CronJob.
 	JobTemplate batchv1.JobTemplateSpec `json:"jobTemplate"`
 
-	// +kubebuilder:validation:Minimum=0
-
-	// The number of successful finished jobs to retain.
+	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
-	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
-
 	// +kubebuilder:validation:Minimum=0
+	SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`
 
-	// The number of failed finished jobs to retain.
+	// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
 
 	// +kubebuilder:docs-gen:collapse=The rest of Spec
@@ -96,19 +93,19 @@ each corresponding Cron "field".
 
 // describes a Cron schedule.
 type CronSchedule struct {
-	// specifies the minute during which the job executes.
+	// minute specifies the minutes during which the job executes.
 	// +optional
 	Minute *CronField `json:"minute,omitempty"`
-	// specifies the hour during which the job executes.
+	// hour specifies the hour during which the job executes.
 	// +optional
 	Hour *CronField `json:"hour,omitempty"`
-	// specifies the day of the month during which the job executes.
+	// dayOfMonth specifies the day of the month during which the job executes.
 	// +optional
 	DayOfMonth *CronField `json:"dayOfMonth,omitempty"`
-	// specifies the month during which the job executes.
+	// month specifies the month during which the job executes.
 	// +optional
 	Month *CronField `json:"month,omitempty"`
-	// specifies the day of the week during which the job executes.
+	// dayOfWeek specifies the day of the week during which the job executes.
 	// +optional
 	DayOfWeek *CronField `json:"dayOfWeek,omitempty"`
 }
@@ -150,11 +147,11 @@ type CronJobStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	// A list of pointers to currently running jobs.
+	// active defines a list of pointers to currently running jobs.
 	// +optional
 	Active []corev1.ObjectReference `json:"active,omitempty"`
 
-	// Information when was the last time the job was successfully scheduled.
+	// lastScheduleTime defines the information when was the last time the job was successfully scheduled.
 	// +optional
 	LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
 }

hack/docs/internal/cronjob-tutorial/api_design.go

@@ -50,46 +50,43 @@ const cronjobSpecExplaination = `
 `
 
 const cronjobSpecStruct = `
+	// schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
 	// +kubebuilder:validation:MinLength=0
-
-	// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
+	// +required
 	Schedule string` + " `" + `json:"schedule"` + "`" + `
 
-	// +kubebuilder:validation:Minimum=0
-
-	// Optional deadline in seconds for starting the job if it misses scheduled
+	// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
 	// time for any reason.  Missed jobs executions will be counted as failed ones.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	StartingDeadlineSeconds *int64` + " `" + `json:"startingDeadlineSeconds,omitempty"` + "`" + `
 
-	// Specifies how to treat concurrent executions of a Job.
+	// concurrencyPolicy specifies how to treat concurrent executions of a Job.
 	// Valid values are:
 	// - "Allow" (default): allows CronJobs to run concurrently;
 	// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 	// - "Replace": cancels currently running job and replaces it with a new one
 	// +optional
 	ConcurrencyPolicy ConcurrencyPolicy` + " `" + `json:"concurrencyPolicy,omitempty"` + "`" + `
 
-	// This flag tells the controller to suspend subsequent executions, it does
+	// suspend tells the controller to suspend subsequent executions, it does
 	// not apply to already started executions.  Defaults to false.
 	// +optional
 	Suspend *bool` + " `" + `json:"suspend,omitempty"` + "`" + `
 
-	// Specifies the job that will be created when executing a CronJob.
+	// jobTemplate defines the job that will be created when executing a CronJob.
 	JobTemplate batchv1.JobTemplateSpec` + " `" + `json:"jobTemplate"` + "`" + `
 
-	// +kubebuilder:validation:Minimum=0
-
-	// The number of successful finished jobs to retain.
+	// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
-	SuccessfulJobsHistoryLimit *int32` + " `" + `json:"successfulJobsHistoryLimit,omitempty"` + "`" + `
-
 	// +kubebuilder:validation:Minimum=0
+	SuccessfulJobsHistoryLimit *int32` + " `" + `json:"successfulJobsHistoryLimit,omitempty"` + "`" + `
 
-	// The number of failed finished jobs to retain.
+	// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
 	// This is a pointer to distinguish between explicit zero and not specified.
 	// +optional
+	// +kubebuilder:validation:Minimum=0
 	FailedJobsHistoryLimit *int32` + " `" + `json:"failedJobsHistoryLimit,omitempty"` + "`" + `
 }
 
@@ -130,11 +127,11 @@ const (
 
 const cronjobList = `
 
-	// A list of pointers to currently running jobs.
+	// active defines a list of pointers to currently running jobs.
 	// +optional
 	Active []corev1.ObjectReference` + " `" + `json:"active,omitempty"` + "`" + `
 
-	// Information when was the last time the job was successfully scheduled.
+	// lastScheduleTime defines when was the last time the job was successfully scheduled.
 	// +optional
 	LastScheduleTime *metav1.Time` + " `" + `json:"lastScheduleTime,omitempty"` + "`" + `
 }

hack/docs/internal/multiversion-tutorial/cronjob_v2.go

@@ -36,19 +36,19 @@ each corresponding Cron "field".
 
 // describes a Cron schedule.
 type CronSchedule struct {
-	// specifies the minute during which the job executes.
+	// minute specifies the minutes during which the job executes.
 	// +optional
 	Minute *CronField ` + "`json:\"minute,omitempty\"`" + `
-	// specifies the hour during which the job executes.
+	// hour specifies the hour during which the job executes.
 	// +optional
 	Hour *CronField ` + "`json:\"hour,omitempty\"`" + `
-	// specifies the day of the month during which the job executes.
+	// dayOfMonth specifies the day of the month during which the job executes.
 	// +optional
 	DayOfMonth *CronField ` + "`json:\"dayOfMonth,omitempty\"`" + `
-	// specifies the month during which the job executes.
+	// month specifies the month during which the job executes.
 	// +optional
 	Month *CronField ` + "`json:\"month,omitempty\"`" + `
-	// specifies the day of the week during which the job executes.
+	// dayOfWeek specifies the day of the week during which the job executes.
 	// +optional
 	DayOfWeek *CronField ` + "`json:\"dayOfWeek,omitempty\"`" + `
 }
@@ -90,52 +90,49 @@ type CronJobStatus struct {
 	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
 	// Important: Run "make" to regenerate code after modifying this file
 
-	// A list of pointers to currently running jobs.
+	// active defines a list of pointers to currently running jobs.
 	// +optional
 	Active []corev1.ObjectReference ` + "`json:\"active,omitempty\"`" + `
 
-	// Information when was the last time the job was successfully scheduled.
+	// lastScheduleTime defines the information when was the last time the job was successfully scheduled.
 	// +optional
 	LastScheduleTime *metav1.Time ` + "`json:\"lastScheduleTime,omitempty\"`" + `
 }
 `
 
 const cronJobSpecReplace = `
-// +kubebuilder:validation:Minimum=0
-
-// Optional deadline in seconds for starting the job if it misses scheduled
+// startingDeadlineSeconds defines in seconds for starting the job if it misses scheduled
 // time for any reason.  Missed jobs executions will be counted as failed ones.
 // +optional
+// +kubebuilder:validation:Minimum=0
 StartingDeadlineSeconds *int64 ` + "`json:\"startingDeadlineSeconds,omitempty\"`" + `
 
-// Specifies how to treat concurrent executions of a Job.
+// concurrencyPolicy defines how to treat concurrent executions of a Job.
 // Valid values are:
 // - "Allow" (default): allows CronJobs to run concurrently;
 // - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
 // - "Replace": cancels currently running job and replaces it with a new one
 // +optional
 ConcurrencyPolicy ConcurrencyPolicy ` + "`json:\"concurrencyPolicy,omitempty\"`" + `
 
-// This flag tells the controller to suspend subsequent executions, it does
+// suspend tells the controller to suspend subsequent executions, it does
 // not apply to already started executions.  Defaults to false.
 // +optional
 Suspend *bool ` + "`json:\"suspend,omitempty\"`" + `
 
-// Specifies the job that will be created when executing a CronJob.
+// jobTemplate defines the job that will be created when executing a CronJob.
 JobTemplate batchv1.JobTemplateSpec ` + "`json:\"jobTemplate\"`" + `
 
-// +kubebuilder:validation:Minimum=0
-
-// The number of successful finished jobs to retain.
+// successfulJobsHistoryLimit defines the number of successful finished jobs to retain.
 // This is a pointer to distinguish between explicit zero and not specified.
 // +optional
-SuccessfulJobsHistoryLimit *int32 ` + "`json:\"successfulJobsHistoryLimit,omitempty\"`" + `
-
 // +kubebuilder:validation:Minimum=0
+SuccessfulJobsHistoryLimit *int32 ` + "`json:\"successfulJobsHistoryLimit,omitempty\"`" + `
 
-// The number of failed finished jobs to retain.
+// failedJobsHistoryLimit defines the number of failed finished jobs to retain.
 // This is a pointer to distinguish between explicit zero and not specified.
 // +optional
+// +kubebuilder:validation:Minimum=0
 FailedJobsHistoryLimit *int32 ` + "`json:\"failedJobsHistoryLimit,omitempty\"`" + `
 
 // +kubebuilder:docs-gen:collapse=The rest of Spec