add docs

On-behalf-of: @SAP christoph.mewes@sap.com

Author: xrstf

pkg/konnector/controllers/cluster/serviceexport/isolation/strategy.go

@@ -23,12 +23,36 @@ import (
 	"k8s.io/apimachinery/pkg/types"
 )
 
+// Strategy implements the namespace/name translation for Kubernetes objects when
+// they are copied from one cluster to another. Not every strategy is necessarily
+// applicable to all circumstances (strategies can be for cluster-scoped or
+// namespaced objects only, check their documentation).
 type Strategy interface {
+	// ToProviderKey translates the namespace/name (collectively called "key") from
+	// the consumer side to the provider side. This function can return a nil key
+	// for invalid/foreign objects, so callers need to be aware.
 	ToProviderKey(consumerKey types.NamespacedName) (*types.NamespacedName, error)
+
+	// ToConsumerKey translates the namespace/name (collectively called "key") from
+	// the provider side to the consumer side. This function can return a nil key
+	// for invalid/foreign objects, so callers need to be aware.
 	ToConsumerKey(providerKey types.NamespacedName) (*types.NamespacedName, error)
 
+	// EnsureProviderKey is very similar to ToProviderKey, but may make changes
+	// on the provider side and return a nil key in case the target key is simply
+	// not ready yet. This is most often the case when waiting for the backend
+	// to assign a namespace for an APIServiceNamespace.
 	EnsureProviderKey(ctx context.Context, consumerKey types.NamespacedName) (*types.NamespacedName, error)
 
+	// MutateMetadataAndSpec mutates the object's content (its main resource) when
+	// syncing from the consumer side to the provide side. This function is also
+	// responsible for applying the translated keys (from ToProviderKey).
 	MutateMetadataAndSpec(consumerObj *unstructured.Unstructured, providerKey types.NamespacedName) error
+
+	// MutateStatus is the opposite of MutateMetadataAndSpec and might mutate the
+	// object status (status subresource) when syncing it back from the provider
+	// cluster to the consumer cluster. This function is also responsible for
+	// applying the consumer key to "rename" the object back to its original name
+	// on the consumer cluster.
 	MutateStatus(providerObj *unstructured.Unstructured, consumerKey types.NamespacedName) error
 }