Clean up docs

This cleans up the existing docs, clarifying working, improving spacing,
and making sure all packages have docs.

pkg/cache/cache.go

@@ -34,17 +34,20 @@ import (
 
 var log = logf.RuntimeLog.WithName("object-cache")
 
-// Cache implements CacheReader by reading objects from a cache populated by InformersMap
+// Cache knows how to load Kubernetes objects, fetch informers to request
+// to receive events for Kubernetes objects (at a low-level),
+// and add indicies to fields on the objects stored in the cache.
 type Cache interface {
-	// Cache implements the client CacheReader
+	// Cache acts as a client to objects stored in the cache.
 	client.Reader
 
-	// Cache implements InformersMap
+	// Cache loads informers and adds field indicies.
 	Informers
 }
 
-// Informers knows how to create or fetch informers for different group-version-kinds.
-// It's safe to call GetInformer from multiple threads.
+// Informers knows how to create or fetch informers for different
+// group-version-kinds, and add indicies to those informers.  It's safe to call
+// GetInformer from multiple threads.
 type Informers interface {
 	// GetInformer fetches or constructs an informer for the given object that corresponds to a single
 	// API kind and resource.
@@ -61,15 +64,11 @@ type Informers interface {
 	// WaitForCacheSync waits for all the caches to sync.  Returns false if it could not sync a cache.
 	WaitForCacheSync(stop <-chan struct{}) bool
 
-	// IndexField adds an index with the given field name on the given object type
-	// by using the given function to extract the value for that field.  If you want
-	// compatibility with the Kubernetes API server, only return one key, and only use
-	// fields that the API server supports.  Otherwise, you can return multiple keys,
-	// and "equality" in the field selector means that at least one key matches the value.
-	IndexField(obj runtime.Object, field string, extractValue client.IndexerFunc) error
+	// Informers knows how to add indicies to the caches (informers) that it manages.
+	client.FieldIndexer
 }
 
-// Options are the optional arguments for creating a new InformersMap object
+// Options are the optional arguments for creating a new set of Informers.
 type Options struct {
 	// Scheme is the scheme to use for mapping objects to GroupVersionKinds
 	Scheme *runtime.Scheme
@@ -87,7 +86,7 @@ type Options struct {
 
 var defaultResyncTime = 10 * time.Hour
 
-// New initializes and returns a new Cache
+// New initializes and returns a new Cache.
 func New(config *rest.Config, opts Options) (Cache, error) {
 	opts, err := defaultOpts(config, opts)
 	if err != nil {

pkg/cache/doc.go

@@ -0,0 +1,19 @@
+/*
+Copyright 2019 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+// Package cache provides object caches that act as caching client.Reader
+// instances and help drive Kubernetes-object-based event handlers.
+package cache

pkg/client/apiutil/apimachinery.go

@@ -14,6 +14,9 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package apiutil contains utilities for working with raw Kubernetes
+// API machinery, such as creating RESTMappers and raw REST clients,
+// and extracting the GVK of an object.
 package apiutil
 
 import (

pkg/client/config/doc.go

@@ -14,5 +14,5 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
-// Package config contains libraries for initializing rest configs for talking to the Kubernetes API
+// Package config contains libraries for initializing REST configs for talking to the Kubernetes API
 package config

pkg/client/fake/client.go

@@ -47,6 +47,8 @@ var _ client.Client = &fakeClient{}
 
 // NewFakeClient creates a new fake client for testing.
 // You can choose to initialize it with a slice of runtime.Object.
+// Deprecated: use NewFakeClientWithScheme.  You should always be
+// passing an explicit Scheme.
 func NewFakeClient(initObjs ...runtime.Object) client.Client {
 	return NewFakeClientWithScheme(scheme.Scheme, initObjs...)
 }

pkg/client/fake/doc.go

@@ -23,5 +23,8 @@ You can create a fake client with optional objects.
 	client := NewFakeClient(initObjs...) // initObjs is a slice of runtime.Object
 
 You can invoke the methods defined in the Client interface.
+
+When it doubt, it's almost always better not to use this package and instead use
+envtest.Environment with a real client and API server.
 */
 package fake

pkg/client/split.go

@@ -23,18 +23,20 @@ import (
 	"k8s.io/apimachinery/pkg/runtime"
 )
 
-// DelegatingClient forms an interface Client by composing separate
-// reader, writer and statusclient interfaces.  This way, you can have an Client that
-// reads from a cache and writes to the API server.
+// DelegatingClient forms a Client by composing separate reader, writer and
+// statusclient interfaces.  This way, you can have an Client that reads from a
+// cache and writes to the API server.
 type DelegatingClient struct {
 	Reader
 	Writer
 	StatusClient
 }
 
-// DelegatingReader forms a interface Reader that will cause Get and List
-// requests for unstructured types to use the ClientReader while
-// requests for any other type of object with use the CacheReader.
+// DelegatingReader forms a Reader that will cause Get and List requests for
+// unstructured types to use the ClientReader while requests for any other type
+// of object with use the CacheReader.  This avoids accidentally caching the
+// entire cluster in the common case of loading arbitrary unstructured objects
+// (e.g. from OwnerReferences).
 type DelegatingReader struct {
 	CacheReader  Reader
 	ClientReader Reader

pkg/controller/controller.go

@@ -45,14 +45,16 @@ type Controller interface {
 	// Reconciler is called to Reconciler an object by Namespace/Name
 	reconcile.Reconciler
 
-	// Watch takes events provided by a Source and uses the EventHandler to enqueue reconcile.Requests in
-	// response to the events.
+	// Watch takes events provided by a Source and uses the EventHandler to
+	// enqueue reconcile.Requests in response to the events.
 	//
-	// Watch may be provided one or more Predicates to filter events before they are given to the EventHandler.
-	// Events will be passed to the EventHandler iff all provided Predicates evaluate to true.
+	// Watch may be provided one or more Predicates to filter events before
+	// they are given to the EventHandler.  Events will be passed to the
+	// EventHandler iff all provided Predicates evaluate to true.
 	Watch(src source.Source, eventhandler handler.EventHandler, predicates ...predicate.Predicate) error
 
-	// Start starts the controller.  Start blocks until stop is closed or a controller has an error starting.
+	// Start starts the controller.  Start blocks until stop is closed or a
+	// controller has an error starting.
 	Start(stop <-chan struct{}) error
 }
 

pkg/controller/controllertest/doc.go

@@ -15,4 +15,6 @@ limitations under the License.
 */
 
 // Package controllertest contains fake informers for testing controllers
+// When in doubt, it's almost always better to test against a real API server
+// using envtest.Environment.
 package controllertest

pkg/envtest/doc.go

@@ -15,4 +15,12 @@ limitations under the License.
 */
 
 // Package envtest provides libraries for integration testing by starting a local control plane
+//
+// Control plane binaries (etcd and kube-apiserver) are loaded by default from
+// /usr/local/kubebuilder/bin.  This can be overridden by setting the
+// KUBEBUILDER_ASSETS environment variable, or by directly creating a
+// ControlPlane for the Environment to use.
+//
+// Environment can also be configured to work with an existing cluster, and
+// simply load CRDs and provide client configuration.
 package envtest

pkg/envtest/printer/ginkgo.go

@@ -14,6 +14,8 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 
+// Package printer contains setup for a friendlier Ginkgo printer that's easier
+// to parse by test automation.
 package printer
 
 import (

pkg/envtest/server.go

@@ -73,7 +73,9 @@ type Environment struct {
 	// ControlPlane is the ControlPlane including the apiserver and etcd
 	ControlPlane integration.ControlPlane
 
-	// Config can be used to talk to the apiserver
+	// Config can be used to talk to the apiserver.  It's automatically
+	// populated if not set using the standard controller-runtime config
+	// loading.
 	Config *rest.Config
 
 	// CRDs is a list of CRDs to install

pkg/event/doc.go

@@ -18,8 +18,11 @@ limitations under the License.
 Package event contains the definitions for the Event types produced by source.Sources and transformed into
 reconcile.Requests by handler.EventHandler.
 
-The details of how events are produced and transformed into reconcile.Requests are not something most
-users should need to use or understand.  Instead of working with Events, users should use
-source.Sources and handler.EventHandlers with Controller.Watch.
+You should rarely need to work with these directly -- instead, use Controller.Watch with
+source.Sources and handler.EventHandlers.
+
+Events generally contain both a full runtime.Object that caused the event, as well
+as a direct handle to that object's metadata.  This saves a lot of typecasting in
+code that works with Events.
 */
 package event

pkg/handler/doc.go

@@ -19,6 +19,8 @@ Package handler defines EventHandlers that enqueue reconcile.Requests in respons
 observed from Watching Kubernetes APIs.  Users should provide a source.Source and handler.EventHandler to
 Controller.Watch in order to generate and enqueue reconcile.Request work items.
 
+Generally, following premade event handlers should be sufficient for most use cases:
+
 EventHandlers
 
 EnqueueRequestForObject - Enqueues a reconcile.Request containing the Name and Namespace of the object in the Event.  This will

pkg/leaderelection/doc.go

@@ -15,6 +15,10 @@ limitations under the License.
 */
 
 /*
-Package leaderelection contains a constructors for a leader election resource lock
+Package leaderelection contains a constructors for a leader election resource lock.
+This is used to ensure that multipe copies of a controller manager can be run with
+only one active set of controllers, for active-passive HA.
+
+It uses built-in Kubernetes leader election APIs.
 */
 package leaderelection

pkg/log/log.go

@@ -16,7 +16,21 @@ limitations under the License.
 
 // Package log contains utilities for fetching a new logger
 // when one is not already available.
-// Deprecated: use pkg/log
+//
+// The Log Handle
+//
+// This package contains a root logr.Logger Log.  It may be used to
+// get a handle to whatever the root logging implementation is.  By
+// default, no implementation exists, and the handle returns "promises"
+// to loggers.  When the implementation is set using SetLogger, these
+// "promises" will be converted over to real loggers.
+//
+// Logr
+//
+// All logging in controller-runtime is structured, using a set of interfaces
+// defined by a package called logr
+// (https://godoc.org/github.com/go-logr/logr).  The sub-package zap provides
+// helpers for setting up logr backed by Zap (go.uber.org/zap).
 package log
 
 import (

pkg/manager/manager.go

@@ -84,7 +84,8 @@ type Manager interface {
 // Options are the arguments for creating a new Manager
 type Options struct {
 	// Scheme is the scheme used to resolve runtime.Objects to GroupVersionKinds / Resources
-	// Defaults to the kubernetes/client-go scheme.Scheme
+	// Defaults to the kubernetes/client-go scheme.Scheme, but it's almost always a good
+	// idea to pass your own scheme in.
 	Scheme *runtime.Scheme
 
 	// MapperProvider provides the rest mapper used to map go types to Kubernetes APIs
@@ -108,10 +109,12 @@ type Options struct {
 	// will use for holding the leader lock.
 	LeaderElectionID string
 
-	// Namespace if specified restricts the manager's cache to watch objects in the desired namespace
-	// Defaults to all namespaces
-	// Note: If a namespace is specified then controllers can still Watch for a cluster-scoped resource e.g Node
-	// For namespaced resources the cache will only hold objects from the desired namespace.
+	// Namespace if specified restricts the manager's cache to watch objects in
+	// the desired namespace Defaults to all namespaces
+	//
+	// Note: If a namespace is specified, controllers can still Watch for a
+	// cluster-scoped resource (e.g Node).  For namespaced resources the cache
+	// will only hold objects from the desired namespace.
 	Namespace string
 
 	// MetricsBindAddress is the TCP address that the controller should bind to
@@ -143,13 +146,18 @@ type NewCacheFunc func(config *rest.Config, opts cache.Options) (cache.Cache, er
 type NewClientFunc func(cache cache.Cache, config *rest.Config, options client.Options) (client.Client, error)
 
 // Runnable allows a component to be started.
+// It's very important that Start blocks until
+// it's done running.
 type Runnable interface {
-	// Start starts running the component.  The component will stop running when the channel is closed.
-	// Start blocks until the channel is closed or an error occurs.
+	// Start starts running the component.  The component will stop running
+	// when the channel is closed.  Start blocks until the channel is closed or
+	// an error occurs.
 	Start(<-chan struct{}) error
 }
 
-// RunnableFunc implements Runnable
+// RunnableFunc implements Runnable using a function.
+// It's very important that the given function block
+// until it's done running.
 type RunnableFunc func(<-chan struct{}) error
 
 // Start implements Runnable