Improve comments and function names

Author: josvazg

internal/autogen/translate/crds/crds.go

@@ -23,7 +23,8 @@ import (
 	apiextensionsv1 "k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1"
 )
 
-// AssertMajorVersion checks the given majorVersion exists for the given kind and CRD version
+// AssertMajorVersion checks the given majorVersion exists for the given kind
+// and CRD version
 func AssertMajorVersion(specVersion *apiextensionsv1.CustomResourceDefinitionVersion, kind string, majorVersion string) error {
 	props, err := GetOpenAPIProperties(kind, specVersion)
 	if err != nil {
@@ -57,7 +58,8 @@ func CompileCRDSchema(openAPISchema *apiextensionsv1.JSONSchemaProps) (*jsonsche
 	return schema, nil
 }
 
-// SelectVersion returns the version from the CRD spec that matches the given version string
+// SelectVersion returns the version from the CRD spec that matches the given
+// version string
 func SelectVersion(spec *apiextensionsv1.CustomResourceDefinitionSpec, version string) *apiextensionsv1.CustomResourceDefinitionVersion {
 	if len(spec.Versions) == 0 {
 		return nil
@@ -73,7 +75,8 @@ func SelectVersion(spec *apiextensionsv1.CustomResourceDefinitionSpec, version s
 	return nil
 }
 
-// GetOpenAPIProperties digs up the schema properties of a given kind on a given CRD version
+// GetOpenAPIProperties digs up the schema properties of a given kind on a given
+// CRD version
 func GetOpenAPIProperties(kind string, version *apiextensionsv1.CustomResourceDefinitionVersion) (map[string]apiextensionsv1.JSONSchemaProps, error) {
 	if version == nil {
 		return nil, fmt.Errorf("missing version (nil) from %v spec", kind)
@@ -90,7 +93,8 @@ func GetOpenAPIProperties(kind string, version *apiextensionsv1.CustomResourceDe
 	return version.Schema.OpenAPIV3Schema.Properties, nil
 }
 
-// GetSpecPropertiesFor takes the properties value of a given field of a kind's properties set
+// GetSpecPropertiesFor takes the properties value of a given field of a kind's
+// properties set
 func GetSpecPropertiesFor(kind string, props map[string]apiextensionsv1.JSONSchemaProps, field string) (map[string]apiextensionsv1.JSONSchemaProps, error) {
 	prop, ok := props[field]
 	if !ok {

internal/autogen/translate/crds/parse.go

@@ -38,7 +38,7 @@ var (
 
 // Parse scans a YAML stream and returns the next CRD found.
 // If more than one CRD is present in the stream, calling again
-// on the same stream will return the next CRD found.
+// on the same stream returns the next CRD found.
 func Parse(scanner *bufio.Scanner) (*apiextensionsv1.CustomResourceDefinition, error) {
 	var buffer bytes.Buffer
 
@@ -80,6 +80,8 @@ func Parse(scanner *bufio.Scanner) (*apiextensionsv1.CustomResourceDefinition, e
 	return nil, io.EOF
 }
 
+// Decode reads raw content as bytes and tries to convertdecode as a CRD schema, or
+// will return an error if decoding fails
 func Decode(content []byte) (*apiextensionsv1.CustomResourceDefinition, error) {
 	sch := runtime.NewScheme()
 	_ = scheme.AddToScheme(sch)

internal/autogen/translate/refs/handler.go

@@ -37,67 +37,79 @@ type Handler struct {
 	expand bool
 }
 
+// NewHandler creates the basic context to expand or collapse references, such
+// context requires the Kubernetes object being translated and its dependencies
 func NewHandler(main client.Object, deps []client.Object) *Handler {
 	return &Handler{context: newMapContext(main, deps)}
 }
 
-func (h *Handler) ExpandReferences(obj, mappings map[string]any, fields ...string) error {
+// ExpandReferences uses the handler context to expand references on a given
+// unstructured value matching the main object being translated, using the
+// given reference mappings and acting on a particular path og the value object
+func (h *Handler) ExpandReferences(obj, mappings map[string]any, path ...string) error {
 	h.expand = true
 
-	props, err := accessMappingPropsAt(mappings, fields)
+	props, err := accessMappingPropsAt(mappings, path)
 	if errors.Is(err, unstructured.ErrNotFound) {
 		return nil
 	} else if err != nil {
 		return fmt.Errorf("failed to access mappings to expand references: %w", err)
 	}
 
-	field, err := unstructured.AccessField[map[string]any](obj, fields...)
+	field, err := unstructured.GetField[map[string]any](obj, path...)
 	if err != nil {
-		return fmt.Errorf("failed to access object's %v: %w", fields, err)
+		return fmt.Errorf("failed to access object's %v: %w", path, err)
 	}
 	if err := h.scanProperties([]string{}, props, field); err != nil {
-		return fmt.Errorf("failed to expand references at %v: %w", fields, err)
+		return fmt.Errorf("failed to expand references at %v: %w", path, err)
 	}
 	return nil
 }
 
-func (h *Handler) CollapseReferences(obj, mappings map[string]any, fields ...string) error {
+// CollapseReferences uses the handler context to collapse references on a given
+// unstructured value matching the main object being translated, using the
+// given reference mappings and acting on a particular path of the value object
+func (h *Handler) CollapseReferences(obj, mappings map[string]any, path ...string) error {
 	h.expand = false
 
-	props, err := accessMappingPropsAt(mappings, fields)
+	props, err := accessMappingPropsAt(mappings, path)
 	if errors.Is(err, unstructured.ErrNotFound) {
 		return nil
 	} else if err != nil {
 		return fmt.Errorf("failed to access mappings to collapse references: %w", err)
 	}
 
-	field, err := unstructured.AccessField[map[string]any](obj, fields...)
+	field, err := unstructured.GetField[map[string]any](obj, path...)
 	if err != nil {
-		return fmt.Errorf("failed to access object's %v: %w", fields, err)
+		return fmt.Errorf("failed to access object's %v: %w", path, err)
 	}
 
 	if err := h.scanProperties([]string{}, props, field); err != nil {
-		return fmt.Errorf("failed to collapse references at %v: %w", fields, err)
+		return fmt.Errorf("failed to collapse references at %v: %w", path, err)
 	}
 	return nil
 }
 
+// Added returns any kubernetes objects created as references by ExpandReferences
 func (h *Handler) Added() []client.Object {
 	return h.added
 }
 
-func accessMappingPropsAt(mappings map[string]any, fields []string) (map[string]any, error) {
+// accessMappingPropsAt reads the mappings object at a given path
+func accessMappingPropsAt(mappings map[string]any, path []string) (map[string]any, error) {
 	expandedPath := []string{"properties"}
-	for _, field := range fields {
+	for _, field := range path {
 		expandedPath = append(expandedPath, field, "properties")
 	}
-	props, err := unstructured.AccessField[map[string]any](mappings, expandedPath...)
+	props, err := unstructured.GetField[map[string]any](mappings, expandedPath...)
 	if err != nil {
 		return nil, fmt.Errorf("failed to access the API mapping properties for %v: %w", expandedPath, err)
 	}
 	return props, nil
 }
 
+// scanProperties checks an object value path position holding field properties
+// against reference mappings that may apply at that path
 func (m *Handler) scanProperties(path []string, props, obj map[string]any) error {
 	for key, prop := range props {
 		mapping, ok := (prop).(map[string]any)
@@ -111,7 +123,7 @@ func (m *Handler) scanProperties(path []string, props, obj map[string]any) error
 			}
 			continue
 		}
-		rawField, err := unstructured.AccessField[any](obj, key)
+		rawField, err := unstructured.GetField[any](obj, key)
 		if errors.Is(err, unstructured.ErrNotFound) {
 			continue
 		}
@@ -135,8 +147,10 @@ func (m *Handler) scanProperties(path []string, props, obj map[string]any) error
 	return nil
 }
 
+// scanArray checks an object value path position holding an array against
+// reference mappings that may apply at that path
 func (m *Handler) scanArray(path []string, mapping map[string]any, list []any) error {
-	mapItems, err := unstructured.AccessField[map[string]any](mapping, "items", "properties")
+	mapItems, err := unstructured.GetField[map[string]any](mapping, "items", "properties")
 	if err != nil {
 		return fmt.Errorf("failed to access %q: %w", unstructured.Base(path), err)
 	}
@@ -160,9 +174,11 @@ func (m *Handler) scanArray(path []string, mapping map[string]any, list []any) e
 	return nil
 }
 
+// scanObject checks an object value path position holding an object against
+// reference mappings that may apply at that path
 func (m *Handler) scanObject(path []string, mapName string, mapping, obj map[string]any) error {
 	if mapping["properties"] != nil {
-		props, err := unstructured.AccessField[map[string]any](mapping, "properties")
+		props, err := unstructured.GetField[map[string]any](mapping, "properties")
 		if err != nil {
 			return fmt.Errorf("failed to access properties at %q: %w", path, err)
 		}
@@ -174,6 +190,7 @@ func (m *Handler) scanObject(path []string, mapName string, mapping, obj map[str
 	return fmt.Errorf("unsupported extension at %v with fields %v", path, unstructured.FieldsOf(mapping))
 }
 
+// processReference kicks of a reference expansion or collapse
 func (m *Handler) processReference(path []string, mappingName string, mapping, obj map[string]any) error {
 	rm := refMapping{}
 	if err := unstructured.FromUnstructured(&rm, mapping); err != nil {
@@ -186,6 +203,8 @@ func (m *Handler) processReference(path []string, mappingName string, mapping, o
 	return ref.Collapse(m.context, path, obj)
 }
 
+// entryMatchingMapping returns the entry name key and value from an array that
+// matches the reference ebing collapsed or expanded
 func entryMatchingMapping(mapName string, mapping map[string]any, list []any, expand bool) (string, map[string]any, error) {
 	key := mapName
 	if expand {
@@ -200,6 +219,7 @@ func entryMatchingMapping(mapName string, mapping map[string]any, list []any, ex
 	return key, m, err
 }
 
+// findByExistingUniqueKey returns the value of an array holding a given key
 func findByExistingUniqueKey(list []any, key string) (map[string]any, error) {
 	candidates := []map[string]any{}
 	for _, item := range list {

internal/autogen/translate/refs/names.go

@@ -21,6 +21,7 @@ import (
 	"k8s.io/apimachinery/pkg/util/rand"
 )
 
+// HashNames will return a hash corresponding to a name and optional arguments
 func HashNames(name string, args ...string) string {
 	hasher := fnv.New64a()
 	hasher.Write([]byte(name))
@@ -32,6 +33,7 @@ func HashNames(name string, args ...string) string {
 	return rand.SafeEncodeString(fmt.Sprint(rawHash))
 }
 
+// PrefixedName produces {prefix}-{hash} by using HashNames
 func PrefixedName(prefix string, name string, args ...string) string {
 	return fmt.Sprintf("%s-%s", prefix, HashNames(name, args...))
 }