chore(docs): fix javadoc and improve it (#774)

Author: metacosm

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

@@ -1,8 +1,14 @@
 package io.javaoperatorsdk.operator.api.reconciler;
 
 import io.fabric8.kubernetes.api.model.HasMetadata;
+import io.javaoperatorsdk.operator.processing.event.source.EventSource;
 import io.javaoperatorsdk.operator.processing.event.source.ResourceCache;
 
+/**
+ * Contextual information made available to prepare event sources.
+ *
+ * @param <P> the type associated with the primary resource that is handled by your reconciler
+ */
 public class EventSourceInitializationContext<P extends HasMetadata> {
 
   private final ResourceCache<P> primaryCache;
@@ -11,6 +17,11 @@ public EventSourceInitializationContext(ResourceCache<P> primaryCache) {
     this.primaryCache = primaryCache;
   }
 
+  /**
+   * Retrieves the cache that an {@link EventSource} can query to retrieve primary resources
+   *
+   * @return the primary resource cache
+   */
   public ResourceCache<P> getPrimaryCache() {
     return primaryCache;
   }

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

@@ -16,8 +16,8 @@ public interface EventSourceInitializer<P extends HasMetadata> {
   /**
    * Prepares a list of {@link EventSource} implementations to be registered by the SDK.
    * 
-   * @param primaryCache a cache providing direct access to primary resources so that event sources
-   *        can extract relevant information from primary resources as needed
+   * @param context a {@link EventSourceInitializationContext} providing access to information
+   *        useful to event sources
    */
   List<EventSource> prepareEventSources(EventSourceInitializationContext<P> context);
 

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

@@ -3,10 +3,30 @@
 import io.javaoperatorsdk.operator.processing.LifecycleAware;
 import io.javaoperatorsdk.operator.processing.event.EventHandler;
 
+/**
+ * Creates an event source to trigger your reconciler whenever something happens to a secondary or
+ * external resource that would not normally trigger your reconciler (as the primary resources are
+ * not changed). To register EventSources with so that your reconciler is triggered, please make
+ * your reconciler implement
+ * {@link io.javaoperatorsdk.operator.api.reconciler.EventSourceInitializer}.
+ */
 public interface EventSource extends LifecycleAware {
+
+  /**
+   * An optional name for your EventSource. This is only required if you need to register multiple
+   * EventSources for the same resource type (e.g. {@code Deployment}).
+   * 
+   * @return the name associated with this EventSource
+   */
   default String name() {
     return getClass().getCanonicalName();
   }
 
+  /**
+   * Sets the {@link EventHandler} that is linked to your reconciler when this EventSource is
+   * registered.
+   * 
+   * @param handler the {@link EventHandler} associated with your reconciler
+   */
   void setEventHandler(EventHandler handler);
 }