diff --git a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PollingEventSource.java b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PollingEventSource.java
index 8701f31182..55609c2918 100644
--- a/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PollingEventSource.java
+++ b/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/polling/PollingEventSource.java
@@ -11,6 +11,35 @@
import io.javaoperatorsdk.operator.processing.event.ResourceID;
import io.javaoperatorsdk.operator.processing.event.source.CachingEventSource;
+/**
+ *
+ * Pols resource (on contrary to {@link PerResourcePollingEventSource}) not per resource bases but
+ * instead to calls supplier periodically and independently of the number of state of custom
+ * resources managed by the operator. It is called on start (synced). This means that when the
+ * reconciler first time executed on startup a poll already happened before. So if the cache does
+ * not contain the target resource it means it is not created yet or was deleted while an operator
+ * was not running.
+ *
+ *
+ * Another caveat with this is if the cached object is checked in the reconciler and created since
+ * not in the cache it should be manually added to the cache, since it can happen that the
+ * reconciler is triggered before the cache is propagated with the new resource from a scheduled
+ * execution. See {@link PollingEventSource##put(ResourceID, Object)}.
+ *
+ * So the generic workflow in reconciler should be:
+ *
+ *
+ * - Check if the cache contains the resource.
+ * - If cache contains the resource reconcile it - compare with target state, update if necessary
+ *
+ * - if cache not contains the resource create it.
+ * - If the resource was created or updated, put the new version of the resource manually to the
+ * cache.
+ *
+ *
+ * @param type of the polled resource
+ * @param primary resource type
+ */
public class PollingEventSource extends CachingEventSource {
private static final Logger log = LoggerFactory.getLogger(PollingEventSource.class);
@@ -29,6 +58,7 @@ public PollingEventSource(Supplier