docs: better explain noFinalizerRemoval use case (#1790)

Author: csviri

Diff for: operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Cleaner.java

@@ -6,7 +6,7 @@ public interface Cleaner<P extends HasMetadata> {
 
   /**
    * This method turns on automatic finalizer usage.
-   *
+   * <p>
    * The implementation should delete the associated component(s). This method is called when an
    * object is marked for deletion. After it's executed the custom resource finalizer is
    * automatically removed by the framework; unless the return value is
@@ -21,9 +21,11 @@ public interface Cleaner<P extends HasMetadata> {
    * @param resource the resource that is marked for deletion
    * @param context the context with which the operation is executed
    * @return {@link DeleteControl#defaultDelete()} - so the finalizer is automatically removed after
-   *         the call. {@link DeleteControl#noFinalizerRemoval()} if you don't want to remove the
-   *         finalizer to indicate that the resource should not be deleted after all, in which case
-   *         the controller should restore the resource's state appropriately.
+   *         the call. Use {@link DeleteControl#noFinalizerRemoval()} when you don't want to remove
+   *         the finalizer immediately but rather wait asynchronously until all secondary resources
+   *         are deleted, thus allowing you to keep the primary resource around until you are sure
+   *         that it can be safely deleted.
+   * @see DeleteControl#noFinalizerRemoval()
    */
   DeleteControl cleanup(P resource, Context<P> context);
 

Diff for: operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/DeleteControl.java

@@ -8,10 +8,25 @@ private DeleteControl(boolean removeFinalizer) {
     this.removeFinalizer = removeFinalizer;
   }
 
+  /**
+   * @return delete control that will remove finalizer.
+   */
   public static DeleteControl defaultDelete() {
     return new DeleteControl(true);
   }
 
+  /**
+   * In some corner cases it might take some time for secondary resources to be cleaned up. In such
+   * situation, the reconciler shouldn't remove the finalizer until it is safe for the primary
+   * resource to be deleted (because, e.g., secondary resources being removed might need its
+   * information to proceed correctly). Using this method will instruct the reconciler to leave the
+   * finalizer in place, presumably to wait for a new reconciliation triggered by event sources on
+   * the secondary resources (e.g. when they are effectively deleted/cleaned-up) to check whether it
+   * is now safe to delete the primary resource and therefore, remove its finalizer by returning
+   * {@link #defaultDelete()} then.
+   *
+   * @return delete control that will not remove finalizer.
+   */
   public static DeleteControl noFinalizerRemoval() {
     return new DeleteControl(false);
   }