From e002278e35aa759d0e32ac67fcbd251d2dc35adc Mon Sep 17 00:00:00 2001
From: Hidde Beydals <hello@hidde.co>
Date: Tue, 14 Apr 2020 10:54:13 +0200
Subject: [PATCH] Improve comments

---
 docs/spec/v1alpha1/common.md           |  6 +++++-
 docs/spec/v1alpha1/gitrepositories.md  | 11 ++++++++---
 docs/spec/v1alpha1/helmcharts.md       |  4 ++--
 docs/spec/v1alpha1/helmrepositories.md |  6 +++++-
 4 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/docs/spec/v1alpha1/common.md b/docs/spec/v1alpha1/common.md
index 092bcec0..70f50011 100644
--- a/docs/spec/v1alpha1/common.md
+++ b/docs/spec/v1alpha1/common.md
@@ -109,11 +109,15 @@ const (
 const (
 	// InitializingReason represents the fact that a given source is being initialized.
 	InitializingReason string = "Initializing"
+
 	// URLInvalidReason represents the fact that a given source has an invalid URL.
 	URLInvalidReason string = "URLInvalid"
+
 	// StorageOperationFailedReason signals a failure caused by a storage operation.
 	StorageOperationFailedReason string = "StorageOperationFailed"
-	// AuthenticationFailedReason represents the fact that the provided credentials are not valid.
+
+	// AuthenticationFailedReason represents the fact that a given secret does not
+	// have the required fields or the provided credentials do not match.
 	AuthenticationFailedReason string = "AuthenticationFailed"
 )
 ```
diff --git a/docs/spec/v1alpha1/gitrepositories.md b/docs/spec/v1alpha1/gitrepositories.md
index 945fe6e8..3fa9274c 100644
--- a/docs/spec/v1alpha1/gitrepositories.md
+++ b/docs/spec/v1alpha1/gitrepositories.md
@@ -9,13 +9,17 @@ an archive.
 Git repository:
 
 ```go
-// GitRepositorySpec defines the desired state of GitRepository.
+// GitRepositorySpec defines the desired state of a Git repository.
 type GitRepositorySpec struct {
 	// The repository URL, can be a HTTP or SSH address.
 	// +kubebuilder:validation:Pattern="^(http|https|ssh)://"
 	URL string `json:"url"`
 
 	// The secret name containing the Git credentials.
+	// For HTTPS repositories the secret must contain username and password
+	// fields.
+	// For SSH repositories the secret must contain identity, identity.pub and
+	// known_hosts fields.
 	// +optional
 	SecretRef *v1.LocalObjectReference `json:"secretRef,omitempty"`
 	
@@ -47,7 +51,7 @@ type GitRepositoryRef struct {
 	SemVer string `json:"semver"`
 
 	// The git commit sha to checkout, if specified branch and tag filters will
-	// be ignored.
+	// ignored.
 	// +optional
 	Commit string `json:"commit"`
 }
@@ -56,7 +60,7 @@ type GitRepositoryRef struct {
 ### Status
 
 ```go
-// GitRepositoryStatus defines the observed state of GitRepository.
+// GitRepositoryStatus defines the observed state of the GitRepository.
 type GitRepositoryStatus struct {
 	// +optional
 	Conditions []SourceCondition `json:"conditions,omitempty"`
@@ -79,6 +83,7 @@ const (
 	// GitOperationSucceedReason represents the fact that the git
 	// clone, pull and checkout operations succeeded.
 	GitOperationSucceedReason string = "GitOperationSucceed"
+
 	// GitOperationFailedReason represents the fact that the git
 	// clone, pull or checkout operations failed.
 	GitOperationFailedReason  string = "GitOperationFailed"
diff --git a/docs/spec/v1alpha1/helmcharts.md b/docs/spec/v1alpha1/helmcharts.md
index 2a27101a..360a1253 100644
--- a/docs/spec/v1alpha1/helmcharts.md
+++ b/docs/spec/v1alpha1/helmcharts.md
@@ -25,8 +25,8 @@ type HelmChartSpec struct {
 	// +required
 	HelmRepositoryRef v1.LocalObjectReference `json:"helmRepositoryRef"`
 
-	// The interval at which to check the Helm repository for updates.
-	// Defaults to the interval of the referenced HelmRepository.
+	// The interval at which to check the referenced HelmRepository index
+	// for updates. Defaults to the interval of the referenced HelmRepository.
 	// +optional
 	Interval metav1.Duration `json:"interval,omitempty"`
 }
diff --git a/docs/spec/v1alpha1/helmrepositories.md b/docs/spec/v1alpha1/helmrepositories.md
index 851a3ac1..1942129c 100644
--- a/docs/spec/v1alpha1/helmrepositories.md
+++ b/docs/spec/v1alpha1/helmrepositories.md
@@ -18,6 +18,9 @@ type HelmRepositorySpec struct {
     
 	// The name of the secret containing authentication credentials
 	// for the Helm repository.
+	// For HTTP/S basic auth the secret must contain username and password
+	// fields.
+	// For TLS the secret must contain caFile, keyFile and caCert fields.
 	// +optional
 	SecretRef *v1.LocalObjectReference `json:"secretRef,omitempty"`
 
@@ -30,7 +33,7 @@ type HelmRepositorySpec struct {
 ### Status
 
 ```go
-// HelmRepositoryStatus defines the observed state of HelmRepository
+// HelmRepositoryStatus defines the observed state of the HelmRepository.
 type HelmRepositoryStatus struct {
 	// +optional
 	Conditions []SourceCondition `json:"conditions,omitempty"`
@@ -52,6 +55,7 @@ const (
 	// IndexationFailedReason represents the fact that the indexation
 	// of the given Helm repository failed.
 	IndexationFailedReason  string = "IndexationFailed"
+
 	// IndexationSucceededReason represents the fact that the indexation
 	// of the given Helm repository succeeded.
 	IndexationSucceedReason string = "IndexationSucceed"