Inline doc overhaul

Trying to make the inline doc more accurate, and to document the less
obvious things.

Author: bpineau

config/config.go

@@ -10,9 +10,9 @@ import (
 	"k8s.io/client-go/rest"
 )
 
-// KfConfig is the configuration struct, passed to controllers's Init()
+// KfConfig holds the configuration options passed at launch time (and the rest client)
 type KfConfig struct {
-	// When DryRun is true, we display but don't really send notifications
+	// When DryRun is true, we don't write to disk and we don't commit/push
 	DryRun bool
 
 	// Logger should be used to send all logs
@@ -21,7 +21,7 @@ type KfConfig struct {
 	// Client represents a connection to a Kubernetes cluster
 	Client *rest.Config
 
-	// GitURL is the address of the git repository
+	// GitURL is the address of a remote git repository
 	GitURL string
 
 	// LocalDir is the local path where we'll serialize cluster objets

pkg/client/client.go

@@ -1,4 +1,4 @@
-// Package client  initialize a Kubernete's client-go rest.Config or clientset
+// Package client initialize a Kubernete's client-go rest.Config or clientset
 package client
 
 import (
@@ -14,9 +14,9 @@ import (
 	_ "k8s.io/client-go/plugin/pkg/client/auth/gcp"
 )
 
-// NewRestConfig create a *rest.Config, using the kubectl paths and priorities:
-// - Command line flags (api-server and/or kubeconfig path) have higher priorities
-// - Else, use the config file path in KUBECONFIG environment variable, if any
+// NewRestConfig create a *rest.Config, trying to mimic kubectl behavior:
+// - Explicit user provided api-server (and/or kubeconfig path) have higher priorities
+// - Else, use the config file path in KUBECONFIG environment variable (if any)
 // - Else, use the config file in ~/.kube/config, if any
 // - Else, consider we're running in cluster (in a pod), and use the pod's service
 //   account and cluster's kubernetes.default service.
@@ -45,8 +45,6 @@ func NewRestConfig(apiserver string, kubeconfig string) (*rest.Config, error) {
 }
 
 // NewClientSet create a clientset (a client connection to a Kubernetes cluster).
-// It will connect using the optional apiserver or kubeconfig options, or will
-// default to the automatic, in cluster settings.
 func NewClientSet(apiserver string, kubeconfig string) (*kubernetes.Clientset, error) {
 	config, err := NewRestConfig(apiserver, kubeconfig)
 	if err != nil {

pkg/controller/controller.go

@@ -1,3 +1,8 @@
+// Package controller list and keep watching a specific Kubernetes resource kind
+// (ie. "apps/v1 Deployment", "v1 Namespace", etc) and notifies a recorder whenever
+// a change happens (an object changed, was created, or deleted). This is a generic
+// implementation: the resource kind to watch is provided at runtime. We should
+// start several such controllers to watch for distinct resources.
 package controller
 
 import (
@@ -159,7 +164,7 @@ func (c *Controller) processItem(key string) error {
 
 	obj := rawobj.(*unstructured.Unstructured).DeepCopy()
 
-	// clean non exportable fields
+	// clear irrelevant attributes
 	uc := obj.UnstructuredContent()
 	md := uc["metadata"].(map[string]interface{})
 	delete(uc, "status")

pkg/controller/observer.go

@@ -1,5 +1,10 @@
 package controller
 
+// An observer polls the Kubernetes api-server to discover all supported
+// API groups/object kinds, and launch a new controller for each of them.
+// Due to CRD/TPR, new API groups / object kinds may appear at any time,
+// that's why we keep polling the API server.
+
 import (
 	"fmt"
 	"strings"
@@ -18,7 +23,7 @@ import (
 
 const discoveryInterval = 60 * time.Second
 
-// Observer manage kubernetes controllers
+// Observer watch api-server and manage kubernetes controllers
 type Observer struct {
 	stop   chan struct{}
 	done   chan struct{}
@@ -39,7 +44,8 @@ type gvk struct {
 
 type resources map[string]*gvk
 
-// NewObserver creates a new observer, to create an manage Kubernetes controllers
+// NewObserver returns a new observer, that will watch for api resource kinds
+// and create new controllers for each one.
 func NewObserver(config *config.KfConfig, evch chan Event) *Observer {
 	return &Observer{
 		config: config,
@@ -164,7 +170,7 @@ func (c *Observer) expandAndFilterAPIResources(groups []*metav1.APIResourceList)
 	}
 
 	// remove lower priorities "cohabitations". cf. kubernetes/cmd/kube-apiserver/app/server.go
-	// (the api server may expose some resources under several api groups for backward compat...)
+	// (the api-server may expose a resource under several api groups, for backward compat)
 	for preferred, obsolete := range preferredVersions {
 		if _, ok := resources[preferred]; ok {
 			delete(resources, obsolete)

pkg/health/health.go

@@ -1,4 +1,4 @@
-// Package health serves healthchecks over HTTP at /health endpoint.
+// Package health serves health checks over HTTP at /health endpoint.
 package health
 
 import (

pkg/recorder/recorder.go

@@ -1,3 +1,5 @@
+// Package recorder listen for events notification from controllers,
+// and persists those events' content as files on disk.
 package recorder
 
 import (
@@ -12,6 +14,9 @@ import (
 	"github.com/bpineau/katafygio/pkg/controller"
 )
 
+// activeFiles will contain a list of active (present in cluster) objets; we'll
+// use that to periodically find and garbage collect stale objets in the git repos
+// (ie. if some objects were delete from cluster while katafygio was not running).
 type activeFiles map[string]bool
 
 // Listener receive events from controllers and save them to disk as yaml files
@@ -33,7 +38,7 @@ func New(config *config.KfConfig, evchan chan controller.Event) *Listener {
 	}
 }
 
-// Start receive events and persists them to disk as files
+// Start receive events and saves them to disk as files
 func (w *Listener) Start() *Listener {
 	w.config.Logger.Info("Starting event recorder")
 	err := os.MkdirAll(filepath.Clean(w.config.LocalDir), 0700)

pkg/run/run.go

@@ -1,5 +1,5 @@
-// Package run implements the main katafygio's loop, by
-// the services and controllers.
+// Package run implements the main katafygio's loop, starting and
+// stopping all services and controllers.
 package run
 
 import (

pkg/store/git/git.go

@@ -1,8 +1,12 @@
-// I'd love a working pure Go implementation. I can't find any though, src-d/go-git
-// being innapropriate due to https://github.com/src-d/go-git/issues/793 and
-// https://github.com/src-d/go-git/issues/785 .
-
-// Package git stores changes a in a git repository
+// We'd love a working pure Go implementation. But so far we didn't find any
+// that would work for us. src-d/go-git is innapropriate due to
+// https://github.com/src-d/go-git/issues/793 and
+// https://github.com/src-d/go-git/issues/785 . And binding to the libgit C lib
+// aren't pure Go either. So we need the git binary for now.
+
+// Package git makes a git repository out of a local directory, keeps the
+// content committed when the directory changes, and optionaly (if a remote
+// repos url is provided), keep it in sync with a remote repository.
 package git
 
 import (
@@ -34,13 +38,13 @@ type Store struct {
 	donech   chan struct{}
 }
 
-// New instantiate a new Store
+// New instantiate a new git Store
 func New(config *config.KfConfig) *Store {
 	return &Store{
 		Logger:   config.Logger,
 		URL:      config.GitURL,
 		LocalDir: config.LocalDir,
-		Author:   "Katafygio", // XXX maybe this could be a cli option
+		Author:   "Katafygio", // XXX should we expose a cli option for that?
 		Email:    "katafygio@localhost",
 		Msg:      "Kubernetes cluster change",
 		DryRun:   config.DryRun,