From 03636fb062298d7ab2a748efda84a7fa798abd5f Mon Sep 17 00:00:00 2001
From: everettraven <everettraven@gmail.com>
Date: Wed, 10 Apr 2024 13:48:48 -0400
Subject: [PATCH] update godoc comments

Signed-off-by: everettraven <everettraven@gmail.com>
---
 pkg/kapp/crdupgradesafety/change_validator.go | 41 +++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/pkg/kapp/crdupgradesafety/change_validator.go b/pkg/kapp/crdupgradesafety/change_validator.go
index 167435d97..8b2f6de98 100644
--- a/pkg/kapp/crdupgradesafety/change_validator.go
+++ b/pkg/kapp/crdupgradesafety/change_validator.go
@@ -69,7 +69,11 @@ func EnumChangeValidation(diff FieldDiff) (bool, error) {
 	return handled(), nil
 }
 
+// ChangeValidator is a Validation implementation focused on
+// handling updates to existing fields in a CRD
 type ChangeValidator struct {
+    // Validations is a slice of ChangeValidations
+    // to run against each changed field
 	Validations []ChangeValidation
 }
 
@@ -77,6 +81,18 @@ func (cv *ChangeValidator) Name() string {
 	return "ChangeValidator"
 }
 
+// Validate will compare each version in the provided existing and new CRDs.
+// Since the ChangeValidator is tailored to handling updates to existing fields in
+// each version of a CRD. As such the following is assumed:
+// - Validating the removal of versions during an update is handled outside of this
+// validator. If a version in the existing version of the CRD does not exist in the new
+// version that version of the CRD is skipped in this validator.
+// - Removal of existing fields is unsafe. Regardless of whether or not this is handled
+// by a validator outside this one, if a field is present in a version provided by the existing CRD
+// but not present in the same version provided by the new CRD this validation will fail.
+//
+// Additionally, any changes that are not validated and handled by the known ChangeValidations
+// are deemed as unsafe and returns an error.
 func (cv *ChangeValidator) Validate(old, new v1.CustomResourceDefinition) error {
 	errs := []error{}
 	for _, version := range old.Spec.Versions {
@@ -124,8 +140,30 @@ type FieldDiff struct {
 	new *v1.JSONSchemaProps
 }
 
+// FlatSchema is a flat representation of a CRD schema.
 type FlatSchema map[string]*v1.JSONSchemaProps
 
+// FlattenSchema takes in a CRD version OpenAPIV3Schema and returns
+// a flattened representation of it. For example, a CRD with a schema of:
+// ```yaml
+//  ...
+//  spec:
+//    type: object
+//    properties:
+//      foo:
+//        type: string
+//      bar:
+//        type: string
+//  ...
+// ```
+// would be represented as:
+// map[string]*v1.JSONSchemaProps{
+//    "^": {},
+//    "^.spec": {},
+//    "^.spec.foo": {},
+//    "^.spec.bar": {},
+// }
+// where "^" represents the "root" schema
 func FlattenSchema(schema *v1.JSONSchemaProps) FlatSchema {
 	fieldMap := map[string]*v1.JSONSchemaProps{}
 
@@ -141,6 +179,9 @@ func FlattenSchema(schema *v1.JSONSchemaProps) FlatSchema {
 	return fieldMap
 }
 
+// CalculateFlatSchemaDiff finds fields in a FlatSchema that are different
+// and returns a mapping of field --> old and new field schemas. If a field
+// exists in the old FlatSchema but not the new an empty diff mapping and an error is returned.
 func CalculateFlatSchemaDiff(o, n FlatSchema) (map[string]FieldDiff, error) {
 	diffMap := map[string]FieldDiff{}
 	for field, schema := range o {