Tweak comments

Author: tardieu

internal/controller/appwrapper_controller.go

@@ -68,7 +68,8 @@ type PodCounts struct {
 // Reconcile one AppWrapper or dispatch next AppWrapper
 // Normal reconciliations "namespace/name" implement all phase transitions except for Queued->Dispatching
 // Queued->Dispatching transitions happen as part of a special "*/*" reconciliation
-// In a "*/*" invocation, we first decide which AppWrapper to dispatch then make the transition
+// In a "*/*" reconciliation, we first decide the AppWrapper to dispatch (dispatchNext)
+// We then dispatch this AppWrapper (Queued->Dispatching transition)
 func (r *AppWrapperReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
 	log := log.FromContext(ctx)
 

internal/controller/timings.go

@@ -23,22 +23,22 @@ import (
 // This file defines all the time constants used in mcad
 
 const (
+	// Timeouts
+	requeuingTimeout       = 2 * time.Minute // minimum wait before aborting Requeuing
+	dispatchingTimeout     = 2 * time.Minute // minimum wait before aborting Dispatching
+	runningTimeout         = 5 * time.Minute // minimum wait before aborting Running
+	cacheConflictTimeout   = 5 * time.Minute // minimum wait before invalidating the cache
+	clusterCapacityTimeout = time.Minute     // how long to cache cluster capacity
+
 	// Cluster capacity is only refreshed when trying to dispatch AppWrappers and only after
-	// the previous measurement has timed out, so it is necessary to trigger dispatch on
+	// the previous measurement has timed out, so it is necessary to call dispatchNext on
 	// a regular basis (we do) to ensure we detect new capacity (such as new schedulable nodes)
-	clusterCapacityTimeout = time.Minute // how long to cache cluster capacity
-
-	cacheConflictTimeout = 5 * time.Minute // when to give up on a cache conflict
-
-	// Timeouts
-	requeuingTimeout   = 2 * time.Minute // minimum wait before aborting Requeuing
-	dispatchingTimeout = 2 * time.Minute // minimum wait before aborting Dispatching
-	runningTimeout     = 5 * time.Minute // minimum wait before aborting Running
 
 	// RequeueAfter delays
-	// This is the maximum delay before the next reconciliation event but reconciliation
-	// may be triggered earlier due for instance to pod phase changes. Moreover, the reconciliation
-	// itself may be delayed due to the on-going reconciliation of other events.
-	runDelay      = time.Minute // maximum delay before next reconciliation when running pods
-	dispatchDelay = time.Minute // maximum delay before next dispatch attempt with queued AppWrappers
+	runDelay      = time.Minute // maximum delay before next reconciliation of a Running AppWrapper
+	dispatchDelay = time.Minute // maximum delay before next "*/*" reconciliation (dispatchNext)
+
+	// The RequeueAfter delay is the maximum delay before the next reconciliation event.
+	// Reconciliation may be triggered earlier due for instance to pod phase changes.
+	// Reconciliation may be delayed due to the on-going reconciliation of other events.
 )