chore(docs): document ResultCondition and how to use it

Signed-off-by: Chris Laprun <claprun@redhat.com>

Author: metacosm

docs/content/en/docs/workflows/_index.md

@@ -49,11 +49,26 @@ reconciliation process.
   See related [integration test](https://github.com/operator-framework/java-operator-sdk/blob/ba5e33527bf9e3ea0bd33025ccb35e677f9d44b4/operator-framework/src/test/java/io/javaoperatorsdk/operator/CRDPresentActivationConditionIT.java).
 
   To have multiple resources of same type with an activation condition is a bit tricky, since you
-  don't want to have multiple `InformerEvetnSource` for the same type, you have to explicitly 
+  don't want to have multiple `InformerEventSource` for the same type, you have to explicitly 
   name the informer for the Dependent Resource (`@KubernetesDependent(informerConfig = @InformerConfig(name = "configMapInformer"))`)
   for all resource of same type with activation condition. This will make sure that only one is registered.
   See details at [low level api](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceRetriever.java#L20-L52).
 
+### Result conditions
+
+While simple conditions are usually enough, it might happen you want to convey extra information as a result of the
+evaluation of the conditions (e.g., to report error messages or because the result of the condition evaluation might be
+interesting for other purposes). In this situation, you should implement `ResultCondition` instead of `Condition` and
+provide an implementation of the `detailedIsMet` method, which allows you to return a more detailed `Result` object via
+which you can provide extra information. The `ResultCondition.Result` interface provides factory method for your
+convenience but you can also provide your own implementation if required.
+
+You can access the results for conditions from the `WorkflowResult` instance that is returned whenever a workflow is
+evaluated. You can access that result from the `ManagedWorkflowAndDependentResourceContext` accessible from the
+reconciliation `Context`. You can then access individual condition results using the `
+getDependentConditionResult` methods. You can see an example of this
+in [this integration test](https://github.com/operator-framework/java-operator-sdk/blob/fd0e92c0de55c47d5df50658cf4e147ee5e6102d/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/workflowallfeature/WorkflowAllFeatureReconciler.java#L44-L49).
+
 ## Defining Workflows
 
 Similarly to dependent resources, there are two ways to define workflows, in managed and standalone

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/workflow/DefaultResult.java

@@ -10,7 +10,7 @@ public DefaultResult(boolean success, T result) {
   }
 
   @Override
-  public T getResult() {
+  public T getDetail() {
     return result;
   }
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/workflow/ResultCondition.java

@@ -4,34 +4,87 @@
 import io.javaoperatorsdk.operator.api.reconciler.Context;
 import io.javaoperatorsdk.operator.api.reconciler.dependent.DependentResource;
 
+/**
+ * A condition that can return extra information in addition of whether it is met or not.
+ * 
+ * @param <R> the resource type this condition applies to
+ * @param <P> the primary resource type associated with the dependent workflow this condition is
+ *        part of
+ * @param <T> the type of the extra information returned by the condition
+ */
 public interface ResultCondition<R, P extends HasMetadata, T> extends Condition<R, P> {
+
+  /**
+   * Checks whether a condition holds true for the specified {@link DependentResource}, returning
+   * additional information as needed.
+   * 
+   * @param dependentResource the {@link DependentResource} for which we want to check the condition
+   * @param primary the primary resource being considered
+   * @param context the current reconciliation {@link Context}
+   * @return a {@link Result} instance containing the result of the evaluation of the condition as
+   *         well as additional detail
+   * @see Condition#isMet(DependentResource, HasMetadata, Context)
+   */
   Result<T> detailedIsMet(DependentResource<R, P> dependentResource, P primary, Context<P> context);
 
   @Override
   default boolean isMet(DependentResource<R, P> dependentResource, P primary, Context<P> context) {
     return detailedIsMet(dependentResource, primary, context).isSuccess();
   }
 
+  /**
+   * Holds a more detailed {@link Condition} result.
+   * 
+   * @param <T> the type of the extra information provided in condition evaluation
+   */
   @SuppressWarnings({"rawtypes", "unchecked"})
   interface Result<T> {
+    /**
+     * A result expressing a condition has been met without extra information
+     */
     ResultCondition.Result metWithoutResult = new DefaultResult(true, null);
 
+    /**
+     * A result expressing a condition has not been met without extra information
+     */
     ResultCondition.Result unmetWithoutResult = new DefaultResult(false, null);
 
+    /**
+     * Creates a {@link Result} without extra information
+     * 
+     * @param success whether or not the condition has been met
+     * @return a {@link Result} without extra information
+     */
     static Result withoutResult(boolean success) {
       return success ? metWithoutResult : unmetWithoutResult;
     }
 
-    static <T> Result<T> withResult(boolean success, T result) {
-      return new DefaultResult<>(success, result);
+    /**
+     * Creates a {@link Result} with the specified condition evaluation result and extra information
+     * 
+     * @param success whether or not the condition has been met
+     * @param detail the extra information that the condition provided during its evaluation
+     * @return a {@link Result} with the specified condition evaluation result and extra information
+     * @param <T> the type of the extra information provided by the condition
+     */
+    static <T> Result<T> withResult(boolean success, T detail) {
+      return new DefaultResult<>(success, detail);
     }
 
     default String asString() {
-      return "Result: " + getResult() + " met: " + isSuccess();
+      return "Detail: " + getDetail() + " met: " + isSuccess();
     }
 
-    T getResult();
+    /**
+     * The extra information provided by the associated {@link ResultCondition} during its evaluation
+     * @return extra information provided by the associated {@link ResultCondition} during its evaluation or {@code null} if none was provided
+     */
+    T getDetail();
 
+    /**
+     * Whether the associated condition held true
+     * @return {@code true} if the associated condition was met, {@code false} otherwise
+     */
     boolean isSuccess();
   }
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/workflow/WorkflowResult.java

@@ -90,7 +90,7 @@ public <T> Optional<T> getDependentConditionResult(DependentResource dependentRe
     try {
       return Optional.ofNullable(results().get(dependentResource))
           .flatMap(detail -> detail.getResultForConditionWithType(conditionType))
-          .map(r -> result[0] = r.getResult())
+          .map(r -> result[0] = r.getDetail())
           .map(expectedResultType::cast);
     } catch (Exception e) {
       throw new IllegalArgumentException("Condition " +

operator-framework-core/src/test/java/io/javaoperatorsdk/operator/processing/dependent/workflow/WorkflowReconcileExecutorTest.java

@@ -600,7 +600,7 @@ public Result<Object> detailedIsMet(DependentResource<Object, HasMetadata> depen
           HasMetadata primary, Context<HasMetadata> context) {
         return new Result<>() {
           @Override
-          public Object getResult() {
+          public Object getDetail() {
             return result;
           }
 
@@ -630,7 +630,7 @@ public Result<Object> detailedIsMet(DependentResource<Object, HasMetadata> depen
           HasMetadata primary, Context<HasMetadata> context) {
         return new Result<>() {
           @Override
-          public Object getResult() {
+          public Object getDetail() {
             return result;
           }