Add doc for controllers

pkg/deploy/controller/config_change_controller.go

@@ -11,6 +11,9 @@ import (
   "github.com/golang/glog"
 )
 
+// ConfigChangeController watches for changes to DeploymentConfigs and regenerates
+// DeploymentConfigs when a change to the PodTemplate of a DeploymentConfig with a 
+// config-change trigger.
 type ConfigChangeController struct {
   DeploymentConfigInterface deploymentConfigInterface
   NextDeploymentConfig      func() *deployapi.DeploymentConfig
@@ -22,10 +25,12 @@ type deploymentConfigInterface interface {
   UpdateDeploymentConfig(kapi.Context, *deployapi.DeploymentConfig) (*deployapi.DeploymentConfig, error)
 }
 
+// Run watches for config change events.
 func (dc *ConfigChangeController) Run() {
   go util.Forever(func() { dc.HandleDeploymentConfig() }, 0)
 }
 
+// HandleDeploymentConfig handles the next DeploymentConfig change that happens.
 func (dc *ConfigChangeController) HandleDeploymentConfig() error {
   config := dc.NextDeploymentConfig()
 

pkg/deploy/controller/deployment_config_controller.go

@@ -9,7 +9,8 @@ import (
 	deployutil "github.com/openshift/origin/pkg/deploy/util"
 )
 
-// A DeploymentConfigController is responsible for implementing the triggers registered by DeploymentConfigs
+// A DeploymentConfigController is responsible for creating new Deployments when
+// a DeploymentConfig is updated with a new LatestVersion.
 type DeploymentConfigController struct {
 	DeploymentInterface deploymentInterface
 
@@ -22,11 +23,12 @@ type deploymentInterface interface {
 	CreateDeployment(ctx kapi.Context, deployment *deployapi.Deployment) (*deployapi.Deployment, error)
 }
 
-// Process deployment config events one at a time
+// Process DeploymentConfig events one at a time.
 func (c *DeploymentConfigController) Run() {
 	go util.Forever(c.HandleDeploymentConfig, 0)
 }
 
+// Process a single DeploymentConfig event.
 func (c *DeploymentConfigController) HandleDeploymentConfig() {
 	config := c.NextDeploymentConfig()
 	ctx := kapi.WithNamespace(kapi.NewContext(), config.Namespace)
@@ -48,6 +50,7 @@ func (c *DeploymentConfigController) HandleDeploymentConfig() {
 	}
 }
 
+// shouldDeploy returns true if the DeploymentConfig should have a new Deployment created.
 func (c *DeploymentConfigController) shouldDeploy(ctx kapi.Context, config *deployapi.DeploymentConfig) (bool, error) {
 	if config.LatestVersion == 0 {
 		glog.Infof("Shouldn't deploy config %s with LatestVersion=0", config.ID)

pkg/deploy/controller/image_change_controller.go

@@ -14,11 +14,12 @@ import (
 	imageapi "github.com/openshift/origin/pkg/image/api"
 )
 
+// ImageChangeController watches for changes to ImageRepositories and regenerates
+// DeploymentConfigs when a new version of a tag referenced by a DeploymentConfig
+// is available.
 type ImageChangeController struct {
 	DeploymentConfigInterface icDeploymentConfigInterface
-
 	NextImageRepository func() *imageapi.ImageRepository
-
 	DeploymentConfigStore cache.Store
 }
 
@@ -27,10 +28,12 @@ type icDeploymentConfigInterface interface {
 	GenerateDeploymentConfig(ctx kapi.Context, id string) (*deployapi.DeploymentConfig, error)
 }
 
+// Process ImageRepository events one by one.
 func (c *ImageChangeController) Run() {
 	go util.Forever(c.OneImageRepo, 0)
 }
 
+// Process the next ImageRepository event.
 func (c *ImageChangeController) OneImageRepo() {
 	imageRepo := c.NextImageRepository()
 	configIDs := []string{}