Clean up docs

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

Author: DirectXMan12

doc.go

@@ -23,7 +23,7 @@ limitations under the License.
 // and uncommon cases should be possible.  In general, controller-runtime tries
 // to guide users towards Kubernetes controller best-practices.
 //
-// Overview
+// Getting Started
 //
 // The main entrypoint for controller-runtime is this root package, which
 // contains all of the common types needed to get started building controllers:
@@ -40,7 +40,7 @@ limitations under the License.
 //
 // Organization
 //
-// A brief walkthrough of the layout of this library can be found below. Each
+// A brief-ish walkthrough of the layout of this library can be found below. Each
 // package contains more information about how to use it.
 //
 // Frequently asked questions about using controller-runtime and designing
@@ -58,8 +58,8 @@ limitations under the License.
 //
 // Controllers
 //
-// Controllers (pkg/controller) handle using events (pkg/events) to eventually
-// trigger reconcile requests.  They may be constructed manually, but are often
+// Controllers (pkg/controller) use events (pkg/events) to eventually trigger
+// reconcile requests.  They may be constructed manually, but are often
 // constructed with a Builder (pkg/builder), which eases the wiring of event
 // sources (pkg/source), like Kubernetes API object changes, to event handlers
 // (pkg/handler), like "enqueue a reconcile request for the object owner".
@@ -75,7 +75,7 @@ limitations under the License.
 // and returns a Response or an error indicating whether to requeue for a
 // second round of processing.
 //
-// Clients (and Caches)
+// Clients and Caches
 //
 // Reconcilers use Clients (pkg/client) to access API objects.  The default
 // client provided by the manager reads from a local shared cache (pkg/cache)
@@ -88,6 +88,12 @@ limitations under the License.
 // may retrieve event recorders (pkg/recorder) to emit events using the
 // manager.
 //
+// Schemes
+//
+// Clients, Caches, and many other things in Kubernetes use Schemes
+// (pkg/runtime/scheme) to associate Go types to Kubernetes API Kinds
+// (Group-Version-Kinds, to be specific).
+//
 // Webhooks
 //
 // Similarly, webhooks (pkg/webhook/admission) may be implemented directly, but
@@ -97,15 +103,16 @@ limitations under the License.
 // Logging and Metrics
 //
 // Logging (pkg/log) in controller-runtime is done via structured logs, using a
-// log interface set called logr (https://godoc.org/github.com/go-logr/logr).
-// While controller-runtime provides easy setup for using Zap
-// (https://go.uber.org/zap, pkg/log/zap), you can provide any implementation
-// of logr as the base logger for controller-runtime.
+// log set of interfaces called logr
+// (https://godoc.org/github.com/go-logr/logr).  While controller-runtime
+// provides easy setup for using Zap (https://go.uber.org/zap, pkg/log/zap),
+// you can provide any implementation of logr as the base logger for
+// controller-runtime.
 //
 // Metrics (pkg/metrics) provided by controller-runtime are registered into a
-// controller-runtime-specific Prometheus metrics registery.  The manager will
-// serve these by default at an HTTP endpoint, and additional metrics may be
-// registered to this Registry as normal.
+// controller-runtime-specific Prometheus metrics registery.  The manager can
+// serve these by an HTTP endpoint, and additional metrics may be registered to
+// this Registry as normal.
 //
 // Testing
 //

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/example_test.go

@@ -199,7 +199,7 @@ func ExampleClient_delete() {
 	_ = c.Delete(context.Background(), u)
 }
 
-// This example shows how to set up and consume a field select over a pod's volumes' secretName field.
+// This example shows how to set up and consume a field selector over a pod's volumes' secretName field.
 func ExampleFieldIndexer_secretName() {
 	// someIndexer is a FieldIndexer over a Cache
 	_ = someIndexer.IndexField(&corev1.Pod{}, "spec.volumes.secret.secretName", func(o runtime.Object) []string {

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
 }