docs: improve javadoc for ResourceOperation on resource cloning and matching (#3502)

Add java doc remark that the desired resource has to be clone (or fresh instance created)
in order to have the maching work correctly

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java

@@ -99,6 +99,15 @@
  * from the desired one, thus also reducing the number of requests made against the Kubernetes API
  * server.
  *
+ * <p><strong>Matching against cached resources.</strong> When matching the actual resource (in most
+ * cases read from the cache) against the desired one for secondary resources, the matching must be
+ * done on a <em>cloned</em> version of the actual resource. Secondary resources are not cloned by
+ * default when read from the cache (see {@link
+ * io.javaoperatorsdk.operator.api.config.ConfigurationService#cloneSecondaryResourcesWhenGettingFromCache()}),
+ * so mutating the resource obtained from the cache while matching would also mutate the copy stored
+ * in the cache. Either clone the resource explicitly before matching, or enable {@link
+ * io.javaoperatorsdk.operator.api.config.ConfigurationService#cloneSecondaryResourcesWhenGettingFromCache()}.
+ *
  * @param <P> the primary resource type on which this object operates
  */
 public class ResourceOperations<P extends HasMetadata> {