docs: improved docs on primary to secondary mapper

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/informer/InformerConfiguration.java

@@ -81,6 +81,16 @@ public <P extends HasMetadata> PrimaryToSecondaryMapper<P> getPrimaryToSecondary
    */
   boolean followControllerNamespaceChanges();
 
+  /**
+   * Returns the configured {@link SecondaryToPrimaryMapper} which will allow JOSDK to identify
+   * which secondary resources are associated with a given primary resource in cases where there is
+   * no explicit reference to the primary resource (e.g. using owner references) in the associated
+   * secondary resources.
+   *
+   * @return the configured {@link SecondaryToPrimaryMapper}
+   * @see SecondaryToPrimaryMapper for more explanations on when using such a mapper is useful /
+   *      needed
+   */
   SecondaryToPrimaryMapper<R> getSecondaryToPrimaryMapper();
 
   Optional<OnAddFilter<R>> onAddFilter();

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/PrimaryToSecondaryMapper.java

@@ -6,10 +6,28 @@
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
 
 /**
- * Primary to Secondary mapper only needed in some cases, typically when there is many-to-one or
- * many-to-many relation between primary and secondary resources. If there is owner reference (or
- * reference with annotations) from secondary to primary this is not needed. See
- * PrimaryToSecondaryIT integration tests that handles many-to-many relationship.
+ * Identifies the set of secondary resources associated with a given primary resource. This is
+ * typically needed when multiple secondary resources can be associated with one or several multiple
+ * primary resources *without* a standard way (e.g. owner reference or annotations) to materialize
+ * that relations. When owner references are present, a {@code PrimaryToSecondaryMapper} instance
+ * should not be needed. In other words, associating such a mapper with your
+ * {@link io.javaoperatorsdk.operator.api.config.informer.InformerConfiguration} is usually needed
+ * when your secondary resources are referenced in some way by your primary resource but that this
+ * link does not exist in the secondary resource information. The mapper implementation instructs
+ * the SDK on how to find all the secondary resources associated with a given primary resource so
+ * that this primary resource can properly be reconciled when changes impact the associated
+ * secondary resources, even though these don't contain any information allowing to make such an
+ * inference.
+ * <p/>
+ * This helps particularly in cases where several secondary resources, listed in some way in the
+ * primary resource, need to or can be created before the primary resource exists. In that
+ * situation, attempting to retrieve the associated secondary resources by calling
+ * {@link io.javaoperatorsdk.operator.api.reconciler.Context#getSecondaryResource(Class)} would fail
+ * without providing a mapper to tell JOSDK how to retrieve the secondary resources.
+ * <p/>
+ * You can see an example of this in action in the <a href=
+ * "https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework/src/test/java/io/javaoperatorsdk/operator/sample/primarytosecondary/JobReconciler.java">Reconciler
+ * for the PrimaryToSecondaryIT</a> integration tests that handles many-to-many relationship.
  *
  * @param <P> primary resource type
  */