Improve comments

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"
 )
 ```

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"

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"`
 }

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"