Merge pull request #2444 from alvaroaleman/clarify-recon

📖 Clarify that the reconcile.Result is ignored on non-nil error

pkg/reconcile/reconcile.go

@@ -89,8 +89,16 @@ instead the reconcile function observes this when reading the cluster state and
 */
 type Reconciler interface {
 	// Reconcile performs a full reconciliation for the object referred to by the Request.
-	// The Controller will requeue the Request to be processed again if an error is non-nil or
-	// Result.Requeue is true, otherwise upon completion it will remove the work from the queue.
+	//
+	// If the returned error is non-nil, the Result is ignored and the request will be
+	// requeued using exponential backoff. The only exception is if the error is a
+	// TerminalError in which case no requeuing happens.
+	//
+	// If the error is nil and the returned Result has a non-zero result.RequeueAfter, the request
+	// will be requeued after the specified duration.
+	//
+	// If the error is nil and result.RequeueAfter is zero and result.Reque is true, the request
+	// will be requeued using exponential backoff.
 	Reconcile(context.Context, Request) (Result, error)
 }