Clarify retry.RetryOnConflict docs

Kubernetes-commit: 23b391e1dd56e84708ac8c95bf6293fe86879c1c

util/retry/util.go

@@ -65,17 +65,36 @@ func OnError(backoff wait.Backoff, retriable func(error) bool, fn func() error)
 	return err
 }
 
-// RetryOnConflict executes the function function repeatedly, retrying if the server returns a conflicting
+// RetryOnConflict is used to make an update to a resource when you have to worry about
-// write. Callers should preserve previous executions if they wish to retry changes. It performs an
+// conflicts caused by other code making unrelated updates to the resource at the same
-// exponential backoff.
+// time. fn should fetch the resource to be modified, make appropriate changes to it, try
+// to update it, and return (unmodified) the error from the update function. On a
+// successful update, RetryOnConflict will return nil. If the update function returns a
+// "Conflict" error, RetryOnConflict will wait some amount of time as described by
+// backoff, and then try again. On a non-"Conflict" error, or if it retries too many times
+// and gives up, RetryOnConflict will return an error to the caller.
 //
-//     var pod *api.Pod
+//     err := retry.RetryOnConflict(retry.DefaultRetry, func() error {
-//     err := RetryOnConflict(DefaultBackoff, func() (err error) {
+//         // Fetch the resource here; you need to refetch it on every try, since
-//       pod, err = c.Pods("mynamespace").UpdateStatus(podStatus)
+//         // if you got a conflict on the last update attempt then you need to get
-//       return
+//         // the current version before making your own changes.
+//         pod, err := c.Pods("mynamespace").Get(name, metav1.GetOptions{})
+//         if err ! nil {
+//             return err
+//         }
+//
+//         // Make whatever updates to the resource are needed
+//         pod.Status.Phase = v1.PodFailed
+//
+//         // Try to update
+//         _, err = c.Pods("mynamespace").UpdateStatus(pod)
+//         // You have to return err itself here (not wrapped inside another error)
+//         // so that RetryOnConflict can identify it correctly.
+//         return err
 //     })
 //     if err != nil {
-//       // may be conflict if max retries were hit
+//         // May be conflict if max retries were hit, or may be something unrelated
+//         // like permissions or a network error
 //         return err
 //     }
 //     ...