Improve docstring comments

Author: simu

certs/ca.go

@@ -182,7 +182,7 @@ func GetServiceCA(ctx context.Context, c client.Client, l logr.Logger, caNamespa
 	return string(caBytes), nil
 }
 
-// InitializeServiceCA checks that
+// initializeServiceCA checks that cert-manager CRDs exist and ensures that the service CA is setup
 func initializeServiceCA(ctx context.Context, l logr.Logger, c client.Client, caNamespace string) error {
 	cmcrd := extv1.CustomResourceDefinition{}
 	if err := c.Get(ctx, client.ObjectKey{Name: "certificates.cert-manager.io"}, &cmcrd); err != nil {

controllers/configmap_controller.go

@@ -36,7 +36,9 @@ const (
 	InjectLabelKey = "service.syn.tools/inject-ca-bundle"
 )
 
-// ConfigMapReconciler reconciles a ConfigMap object
+// ConfigMapReconciler injects the service CA certificate into field `ca.crt`
+// of ConfigMap objects which have the label
+// `service.syn.tools/inject-ca-bundle` set to `true`.
 type ConfigMapReconciler struct {
 	client.Client
 	Scheme      *runtime.Scheme
@@ -47,8 +49,10 @@ type ConfigMapReconciler struct {
 //+kubebuilder:rbac:groups=core,resources=configmaps/status,verbs=get;update;patch
 //+kubebuilder:rbac:groups=core,resources=configmaps/finalizers,verbs=update
 
-// Reconcile is part of the main kubernetes reconciliation loop which aims to
-// move the current state of the cluster closer to the desired state.
+// Reconcile injects the service CA certificate into ConfigMaps which have the
+// `service.syn.tools/inject-ca-bundle` label set to `true`.
+// Please note that the reconciler will requeue requests until the Service CA
+// is created an ready.
 func (r *ConfigMapReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 	l := log.FromContext(ctx).WithValues("namespace", req.Namespace, "name", req.Name)
 

controllers/service_controller.go

@@ -38,7 +38,8 @@ const (
 	ServingCertLabelKey = "service.syn.tools/serving-cert-secret-name"
 )
 
-// ServiceReconciler reconciles a Service object
+// ServiceReconciler reconcile Service objects which have the label
+// `service.syn.tools/serving-cert-secret-name` set.
 type ServiceReconciler struct {
 	client.Client
 	Scheme      *runtime.Scheme
@@ -51,8 +52,13 @@ type ServiceReconciler struct {
 //+kubebuilder:rbac:groups=cert-manager.io,resources=certificates,verbs=get;list;watch;create;update;patch;delete
 //+kubebuilder:rbac:groups=cert-manager.io,resources=certificates/status,verbs=get;update;patch;delete
 
-// Reconcile is part of the main kubernetes reconciliation loop which aims to
-// move the current state of the cluster closer to the desired state.
+// Reconcile creates or updates a cert-manager Certificate resource for
+// services which have label `service.syn.tools/serving-cert-secret-name` set.
+// The Certificate resource is configured to use the Service CA cluster
+// issuer, and the value of the `service.syn.tools/serving-cert-secret-name`
+// label is used as the certificate secret name.
+// Please note that the reconciler will requeue requests until the Service CA
+// is created an ready.
 func (r *ServiceReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 	l := log.FromContext(ctx).WithValues("namespace", req.Namespace, "name", req.Name)