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

It isn't obvious for people new to the project that the returned error
is part of the control flow and that if it is set, the Result will be
ignored. Add some godocs to clarify that.

Author: alvaroaleman

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)
 }