add doc comments to packages

Author: ecordell

NOTICE

@@ -1,4 +1,4 @@
-ktrllib
+controller-idioms
 Copyright 2022 Authzed, Inc
 
 This product includes software developed at

README.md

@@ -147,9 +147,9 @@ secrets, err := secretIndexer.ByIndex("my-index-name", "my-index-value")
 
 ### Controllers and Managers
 
-The `manager` package provides an optional lightweight controller `Manager` abstraction (similar to kubernetes controller manager, or the manager from controller runtime). It also provides a simple `Controller` abstraction and some basic implementations. Both are optional, `ktrllib` can be used without these.
+The `manager` package provides an optional lightweight controller `Manager` abstraction (similar to kubernetes controller manager, or the manager from controller runtime). It also provides a simple `Controller` abstraction and some basic implementations. 
 
-The rest of `ktrllib` can be used without using these if you are already using another solution.
+The rest of `controller-idioms` can be used without using these if you are already using another solution.
 
 #### `Manager`
 

adopt/adopt.go

@@ -39,32 +39,51 @@ import (
 // TODO: a variant where there can only be one owner (label only, fail if labelled for someone else)
 // TODO: a variant where a real client is used to check for existence before applying
 
+// Annotator is any type that can have annotations added to it. All standard
+// applyconfiguration packages from client-go implement this type. Custom types
+// should implement it themselves.
 type Annotator[T any] interface {
 	WithAnnotations(entries map[string]string) T
 }
 
+// Labeler is any type that can have labels added to it. All standard
+// applyconfiguration packages from client-go implement this type. Custom types
+// should implement it themselves.
 type Labeler[T any] interface {
 	WithLabels(entries map[string]string) T
 }
 
+// Adoptable is any type that can be labelled and annotated.
+// Labels are used for including in a watch stream, and annotations are used
+// to indicated ownership by a specific object.
 type Adoptable[T any] interface {
 	Annotator[T]
 	Labeler[T]
 }
 
+// Object is satisfied by any standard kube object.
 type Object interface {
 	comparable
 	runtime.Object
 	metav1.Object
 }
 
+// ApplyFunc should apply a patch defined by the object A with server-side apply
+// and should return the base type. For example a SecretApplyConfiguration would
+// be applied with a client-go Patch call, and return a Secret.
 type ApplyFunc[K Object, A Adoptable[A]] func(ctx context.Context, object A, opts metav1.ApplyOptions) (result K, err error)
 
+// IndexKeyFunc returns the name of an index to use and the value to query it for.
 type IndexKeyFunc func(ctx context.Context) (indexName string, indexValue string)
 
+// Owned is used in object annotations to indicate an object is managed.
 const Owned = "owned"
 
+// AdoptionHandler implements handler.Handler to "adopt" an existing resource
+// under the controller's management. See the package description for more info.
 type AdoptionHandler[K Object, A Adoptable[A]] struct {
+	// OperationsContext allows the adoption handler to control the sync loop
+	// it's called from to deal with transient errors.
 	queue.OperationsContext
 
 	// ControllerFieldManager is the value to use when adopting the object
@@ -88,8 +107,8 @@ type AdoptionHandler[K Object, A Adoptable[A]] struct {
 	// ObjectAdoptedFunc is called when an adoption was performed
 	ObjectAdoptedFunc func(ctx context.Context, obj K)
 
-	// TODO: GetFromCache and Indexer should be replaced with an informer factory that can be
-	//  used to get both
+	// TODO: GetFromCache and Indexer could be replaced with an informerfactory
+	//  that can be used to get both
 
 	// GetFromCache is where we expect to find the object if it is being watched
 	// This will usually be a wrapper around an informer cache `Get`.

bootstrap/cr.go

@@ -1,3 +1,15 @@
+// Package bootstrap implements utilities for boostrapping a kube cluster
+// with resources on controller start.
+//
+// Typically this is used to bootstrap CRDs and CRs (of the types defined by the
+// CRDs) so that a controller can be continuously deployed and still include
+// breaking changes.
+//
+// The bootstrap approach allows the controller to determine when and how to
+// coordinate updates to the apis it manages. It should not typically be used
+// by end-users of an operator, who may be using one or more other tools to
+// manage the deployment of the operator and the resources it manages, and may
+// not wish to grant the privileges required to bootstrap.
 package bootstrap
 
 import (
@@ -20,6 +32,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client"
 )
 
+// KubeResourceObject is satisfied by any standard kube object.
 type KubeResourceObject interface {
 	metav1.Object
 	runtime.Object

cachekeys/keys.go

@@ -1,3 +1,8 @@
+// Package cachekeys provides standard utilites for creating and parsing cache
+// keys for use in client-go caches and workqueus.
+//
+// These allow one to build queues that process multiple types of objects by
+// annotating the standard namespace/name keys with the GVR.
 package cachekeys
 
 import (
@@ -8,10 +13,12 @@ import (
 	"k8s.io/client-go/tools/cache"
 )
 
+// GVRMetaNamespaceKeyer creates a cache/queue key from a gvr and an object key
 func GVRMetaNamespaceKeyer(gvr schema.GroupVersionResource, key string) string {
 	return fmt.Sprintf("%s.%s.%s::%s", gvr.Resource, gvr.Version, gvr.Group, key)
 }
 
+// GVRMetaNamespaceKeyFunc creates cache/queue key from a gvr and an object.
 func GVRMetaNamespaceKeyFunc(gvr schema.GroupVersionResource, obj interface{}) (string, error) {
 	if d, ok := obj.(cache.DeletedFinalStateUnknown); ok {
 		return d.Key, nil
@@ -23,6 +30,7 @@ func GVRMetaNamespaceKeyFunc(gvr schema.GroupVersionResource, obj interface{}) (
 	return GVRMetaNamespaceKeyer(gvr, key), nil
 }
 
+// SplitGVRMetaNamespaceKey splits a cache key into gvr, namespace, and name.
 func SplitGVRMetaNamespaceKey(key string) (gvr *schema.GroupVersionResource, namespace, name string, err error) {
 	before, after, ok := strings.Cut(key, "::")
 	if !ok {

component/component.go

@@ -1,3 +1,16 @@
+// Package component implements a common controller pattern: an object is
+// specified by a user, and another kube object needs to be created in response.
+//
+// `Component`specifies how to find these related objects in the cluster.
+//
+// `ContextHandler` is a handler.Handler implementation that can pick out
+// a component from a cluster and add it into a context.Context key.
+//
+// `EnsureComponent` is a handler.Handler implementation that ensures that a
+// component with a given specification exists. It handles creating the object
+// if it doesn't exist and updating it only if the calculated object has
+// changed. It also cleans up duplicate matching component objects by deleting
+// any that match the component selector but do not match the calculated object.
 package component
 
 import (
@@ -13,21 +26,22 @@ import (
 	"github.com/authzed/controller-idioms/typed"
 )
 
+// KubeObject is satisfied by any standard kube object.
 type KubeObject interface {
 	metav1.Object
 	runtime.Object
 }
 
-// Component represents an KubeObject in the cluster that is "related" to another
-// i.e. a pod would be a component of a deployment (though direct ownership is
+// Component represents a KubeObject in the cluster that is "related" to another
+// i.e. a pod could be a component of a deployment (though direct ownership is
 // not required).
 type Component[K KubeObject] struct {
 	indexer      *typed.Indexer[K]
 	selectorFunc func(ctx context.Context) labels.Selector
 	indexName    string
 }
 
-// NewIndexedComponent creates a component from an index
+// NewIndexedComponent creates a Component from an index
 func NewIndexedComponent[K KubeObject](indexer *typed.Indexer[K], indexName string, selectorFunc func(ctx context.Context) labels.Selector) *Component[K] {
 	return &Component[K]{
 		indexer:      indexer,
@@ -59,13 +73,17 @@ func (c *Component[K]) List(ctx context.Context, indexValue fmt.Stringer) (out [
 }
 
 // HashableComponent is a Component with an annotation that stores a hash of the
-// previous configuration the controller wrote
+// previous configuration written by the controller. The hash is used to
+// determine if work still needs to be done.
 type HashableComponent[K KubeObject] struct {
 	*Component[K]
 	hash.ObjectHasher
 	HashAnnotationKey string
 }
 
+// NewHashableComponent creates HashableComponent from a Component and a
+// hash.ObjectHasher, plus an annotation key to use to store the hash on the
+// object.
 func NewHashableComponent[K KubeObject](component *Component[K], hasher hash.ObjectHasher, key string) *HashableComponent[K] {
 	return &HashableComponent[K]{
 		Component:         component,

component/component_handler.go

@@ -9,7 +9,7 @@ import (
 	"github.com/authzed/controller-idioms/typedctx"
 )
 
-// ContextHandler fills the value for a Key with the result of
+// ContextHandler fills the value for a context.Key with the result of
 // fetching a component.
 type ContextHandler[K KubeObject] struct {
 	owner     typedctx.MustValueContext[types.NamespacedName]
@@ -18,6 +18,7 @@ type ContextHandler[K KubeObject] struct {
 	next      handler.ContextHandler
 }
 
+// NewComponentContextHandler creates a new ContextHandler.
 func NewComponentContextHandler[K KubeObject](contextKey typedctx.SettableContext[[]K], component *Component[K], owner typedctx.MustValueContext[types.NamespacedName], next handler.ContextHandler) *ContextHandler[K] {
 	return &ContextHandler[K]{
 		owner:     owner,

component/ensure_component.go

@@ -12,10 +12,15 @@ import (
 	"github.com/authzed/controller-idioms/typedctx"
 )
 
+// Annotator is any type that can have annotations added to it. All standard
+// applyconfiguration packages from client-go implement this type. Custom types
+// should implement it themselves.
 type Annotator[T any] interface {
 	WithAnnotations(entries map[string]string) T
 }
 
+// EnsureComponentByHash is a handler.Handler implementation that
+// will create a component object and ensure it has the computed spec.
 type EnsureComponentByHash[K KubeObject, A Annotator[A]] struct {
 	*HashableComponent[K]
 	ctrls        *typedctx.Key[queue.Interface]
@@ -27,6 +32,7 @@ type EnsureComponentByHash[K KubeObject, A Annotator[A]] struct {
 
 var _ handler.ContextHandler = &EnsureComponentByHash[*corev1.Service, *applycorev1.ServiceApplyConfiguration]{}
 
+// NewEnsureComponentByHash returns a new EnsureComponentByHash handler.
 func NewEnsureComponentByHash[K KubeObject, A Annotator[A]](
 	component *HashableComponent[K],
 	owner typedctx.MustValueContext[types.NamespacedName],

fileinformer/file_informer.go

@@ -1,3 +1,5 @@
+// Package fileinformer implements a kube-style Informer and InformerFactory
+// that can be used to watch files instead of kube apis.
 package fileinformer
 
 import (
@@ -15,11 +17,14 @@ import (
 	"k8s.io/klog/v2"
 )
 
+// FileGroupVersion is a sythetic GroupVersion that the informers use.
 var FileGroupVersion = schema.GroupVersion{
 	Group:   "//LocalFile",
 	Version: "v1",
 }
 
+// Factory implements dynamicinformer.DynamicSharedInformerFactory, but for
+// starting and managing FileInformers.
 type Factory struct {
 	sync.Mutex
 	informers map[schema.GroupVersionResource]informers.GenericInformer
@@ -30,13 +35,15 @@ type Factory struct {
 
 var _ dynamicinformer.DynamicSharedInformerFactory = &Factory{}
 
+// NewFileInformerFactory creates a new Factory.
 func NewFileInformerFactory() (*Factory, error) {
 	return &Factory{
 		informers:        make(map[schema.GroupVersionResource]informers.GenericInformer),
 		startedInformers: make(map[schema.GroupVersionResource]bool),
 	}, nil
 }
 
+// Start starts watching the files defined byt the informers.
 func (f *Factory) Start(stopCh <-chan struct{}) {
 	f.Lock()
 	defer f.Unlock()
@@ -49,6 +56,7 @@ func (f *Factory) Start(stopCh <-chan struct{}) {
 	}
 }
 
+// ForResource will create an informer for a specific file.
 func (f *Factory) ForResource(gvr schema.GroupVersionResource) informers.GenericInformer {
 	f.Lock()
 	defer f.Unlock()
@@ -72,6 +80,7 @@ func (f *Factory) ForResource(gvr schema.GroupVersionResource) informers.Generic
 	return informer
 }
 
+// WaitForCacheSync waits until all files in the informers have been synced once.
 func (f *Factory) WaitForCacheSync(stopCh <-chan struct{}) map[schema.GroupVersionResource]bool {
 	infs := func() map[schema.GroupVersionResource]cache.SharedIndexInformer {
 		f.Lock()
@@ -93,6 +102,7 @@ func (f *Factory) WaitForCacheSync(stopCh <-chan struct{}) map[schema.GroupVersi
 	return res
 }
 
+// FileInformer is an informer that watches files instead of the kube api.
 type FileInformer struct {
 	fileName string
 	watcher  *fsnotify.Watcher
@@ -101,6 +111,7 @@ type FileInformer struct {
 
 var _ informers.GenericInformer = &FileInformer{}
 
+// NewFileInformer returns a new FileInformer.
 func NewFileInformer(watcher *fsnotify.Watcher, gvr schema.GroupVersionResource) (*FileInformer, error) {
 	return &FileInformer{
 		fileName: gvr.Resource,
@@ -292,3 +303,8 @@ func (f *FileSharedIndexInformer) GetIndexer() cache.Indexer {
 	// TODO implement me
 	panic("implement me")
 }
+
+func (f *FileSharedIndexInformer) SetTransform(handler cache.TransformFunc) error {
+	// TODO implement me
+	panic("implement me")
+}

handler/handler.go

@@ -1,12 +1,5 @@
-package handler
-
-import (
-	"context"
-	"fmt"
-)
-
-// This package contains the basic Handler units used to compose reconciliation
-// loops for a controller.
+// Package handler contains the basic Handler units used to compose
+// reconciliation loops for a controller.
 //
 // You write functions or types that implement the ContextHandler interface, and
 // then compose them via Handlers and Builders.
@@ -17,6 +10,12 @@ import (
 // behavior respectively), so each type has methods to convert between them.
 //
 // See other files for helpers to compose or wrap handlers and builders.
+package handler
+
+import (
+	"context"
+	"fmt"
+)
 
 // ContextHandler is the interface for a "chunk" of reconciliation. It either
 // returns, often by adjusting the current key's place in the queue (i.e. via