fix: javadoc problems preventing snapshot release (#1848)

Author: csviri

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/Operator.java

@@ -43,6 +43,7 @@ public Operator(KubernetesClient kubernetesClient) {
   }
 
   /**
+   * @param configurationService implementation
    * @deprecated Use {@link #Operator(Consumer)} instead
    */
   @Deprecated(forRemoval = true)
@@ -173,6 +174,7 @@ public void stop() throws OperatorException {
    *
    * @param reconciler the reconciler to register
    * @param <P> the {@code CustomResource} type associated with the reconciler
+   * @return registered controller
    * @throws OperatorException if a problem occurred during the registration process
    */
   public <P extends HasMetadata> RegisteredController<P> register(Reconciler<P> reconciler)
@@ -192,6 +194,7 @@ public <P extends HasMetadata> RegisteredController<P> register(Reconciler<P> re
    * @param reconciler part of the reconciler to register
    * @param configuration the configuration with which we want to register the reconciler
    * @param <P> the {@code HasMetadata} type associated with the reconciler
+   * @return registered controller
    * @throws OperatorException if a problem occurred during the registration process
    */
   public <P extends HasMetadata> RegisteredController<P> register(Reconciler<P> reconciler,
@@ -230,6 +233,7 @@ public <P extends HasMetadata> RegisteredController<P> register(Reconciler<P> re
    *
    * @param reconciler part of the reconciler to register
    * @param configOverrider consumer to use to change config values
+   * @return registered controller
    * @param <P> the {@code HasMetadata} type associated with the reconciler
    */
   public <P extends HasMetadata> RegisteredController<P> register(Reconciler<P> reconciler,

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

@@ -199,6 +199,8 @@ default Optional<LeaderElectionConfiguration> getLeaderElectionConfiguration() {
    * if false, the startup will ignore recoverable errors, caused for example by RBAC issues, and
    * will try to reconnect periodically in the background.
    * </p>
+   *
+   * @return actual value described above
    */
   default boolean stopOnInformerErrorDuringStartup() {
     return true;
@@ -208,6 +210,8 @@ default boolean stopOnInformerErrorDuringStartup() {
    * Timeout for cache sync. In other words source start timeout. Note that is
    * "stopOnInformerErrorDuringStartup" is true the operator will stop on timeout. Default is 2
    * minutes.
+   *
+   * @return Duration of sync timeout
    */
   default Duration cacheSyncTimeout() {
     return Duration.ofMinutes(2);
@@ -216,6 +220,8 @@ default Duration cacheSyncTimeout() {
   /**
    * Handler for an informer stop. Informer stops if there is a non-recoverable error. Like received
    * a resource that cannot be deserialized.
+   *
+   * @return an optional InformerStopHandler
    */
   default Optional<InformerStoppedHandler> getInformerStoppedHandler() {
     return Optional.of((informer, ex) -> {

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

@@ -238,6 +238,8 @@ public ResourceClassResolver getResourceClassResolver() {
 
   /**
    * @deprecated Use {@link ConfigurationServiceProvider#overrideCurrent(Consumer)} instead
+   * @param original that will be overriding
+   * @return current overrider
    */
   @Deprecated(since = "2.2.0")
   public static ConfigurationServiceOverrider override(ConfigurationService original) {

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

@@ -106,6 +106,8 @@ public ControllerConfigurationOverrider<R> watchingAllNamespaces() {
   }
 
   /**
+   * @param retry configuration
+   * @return current instance of overrider
    * @deprecated Use {@link #withRetry(Retry)} instead
    */
   @Deprecated(forRemoval = true)

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

@@ -156,6 +156,8 @@ public ResourceEventFilter<P> getEventFilter() {
 
   /**
    * @deprecated Use {@link OnAddFilter}, {@link OnUpdateFilter} and {@link GenericFilter} instead
+   *
+   * @param eventFilter
    */
   @Deprecated(forRemoval = true)
   protected void setEventFilter(ResourceEventFilter<P> eventFilter) {

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

@@ -78,6 +78,8 @@ public <P extends HasMetadata> PrimaryToSecondaryMapper<P> getPrimaryToSecondary
    * {@link io.javaoperatorsdk.operator.RegisteredController}). If true, changing the target
    * namespaces of a controller would result to change target namespaces for the
    * InformerEventSource.
+   *
+   * @return if namespace changes should be followed
    */
   boolean followControllerNamespaceChanges();
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/monitoring/Metrics.java

@@ -23,6 +23,8 @@ public interface Metrics {
 
   /**
    * Do initialization if necessary;
+   *
+   * @param controller callback
    */
   default void controllerRegistered(Controller<? extends HasMetadata> controller) {}
 
@@ -36,6 +38,9 @@ default void controllerRegistered(Controller<? extends HasMetadata> controller)
   default void receivedEvent(Event event, Map<String, Object> metadata) {}
 
   /**
+   * @param metadata additional metadata
+   * @param resourceID of primary resource
+   * @param retryInfo for current execution
    * @deprecated Use {@link #reconcileCustomResource(HasMetadata, RetryInfo, Map)} instead
    */
   @Deprecated(forRemoval = true)
@@ -56,6 +61,9 @@ default void reconcileCustomResource(HasMetadata resource, RetryInfo retryInfo,
   }
 
   /**
+   * @param exception actual exception
+   * @param metadata additional metadata
+   * @param resourceID of primary resource
    * @deprecated Use {@link #failedReconciliation(HasMetadata, Exception, Map)} instead
    */
   @Deprecated(forRemoval = true)
@@ -84,7 +92,7 @@ default void reconciliationExecutionFinished(HasMetadata resource,
       Map<String, Object> metadata) {}
 
   /**
-   *
+   * @param resourceID of primary resource
    * @deprecated Use (and implement) {@link #cleanupDoneFor(ResourceID, Map)} instead
    */
   @Deprecated
@@ -102,7 +110,7 @@ default void cleanupDoneFor(ResourceID resourceID) {
   default void cleanupDoneFor(ResourceID resourceID, Map<String, Object> metadata) {}
 
   /**
-   *
+   * @param resourceID of primary resource
    * @deprecated Use (and implement) {@link #finishedReconciliation(ResourceID, Map)} instead
    */
   @Deprecated
@@ -111,6 +119,8 @@ default void finishedReconciliation(ResourceID resourceID) {
   }
 
   /**
+   * @param resourceID of primary resource
+   * @param metadata additional metadata
    * @deprecated Use {@link #finishedReconciliation(HasMetadata, Map)} instead
    */
   @Deprecated(forRemoval = true)

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

@@ -75,14 +75,22 @@
 
   /**
    * Filter of onAdd events of resources.
+   *
+   * @return on-add filter
    **/
   Class<? extends OnAddFilter> onAddFilter() default OnAddFilter.class;
 
-  /** Filter of onUpdate events of resources. */
+  /**
+   * Filter of onUpdate events of resources.
+   *
+   * @return on-update filter
+   */
   Class<? extends OnUpdateFilter> onUpdateFilter() default OnUpdateFilter.class;
 
   /**
    * Filter applied to all operations (add, update, delete). Used to ignore some resources.
+   *
+   * @return generic filter
    **/
   Class<? extends GenericFilter> genericFilter() default GenericFilter.class;
 

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

@@ -8,6 +8,7 @@ public interface Reconciler<R extends HasMetadata> {
    * The implementation of this operation is required to be idempotent. Always use the UpdateControl
    * object to make updates on custom resource if possible.
    *
+   * @throws Exception from the custom implementation
    * @param resource the resource that has been created or updated
    * @param context the context with which the operation is executed
    * @return UpdateControl to manage updates on the custom resource (usually the status) after

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

@@ -10,6 +10,8 @@ default void useEventSourceWithName(String name) {}
   /**
    * Throws {@link EventSourceNotFoundException} an exception if the target event source to use is
    * not found.
+   *
+   * @param eventSourceRetriever for event sources
    */
   void resolveEventSource(EventSourceRetriever<P> eventSourceRetriever)
       throws EventSourceNotFoundException;

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/dependent/managed/ManagedDependentResourceContext.java

@@ -30,6 +30,7 @@ public interface ManagedDependentResourceContext {
    * the semantics of this operation is defined as removing the mapping associated with the
    * specified key.
    *
+   * @param <T> object type
    * @param key the key identifying which contextual object to add or remove from the context
    * @param value the value to add to the context or {@code null} to remove an existing entry
    *        associated with the specified key

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/Controller.java

@@ -309,6 +309,7 @@ public void start() throws OperatorException {
    * {@link io.javaoperatorsdk.operator.api.config.ControllerConfigurationOverrider#override(ControllerConfiguration)},
    * passing it the controller's original configuration.
    *
+   * @param startEventProcessor if event processing should be started automatically
    * @throws OperatorException if a problem occurred during the registration process
    */
   public synchronized void start(boolean startEventProcessor) throws OperatorException {

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

@@ -61,7 +61,12 @@ public void resolveEventSource(EventSourceRetriever<P> eventSourceRetriever) {
     }
   }
 
-  /** To make this backwards compatible even for respect of overriding */
+  /**
+   * To make this backwards compatible even for respect of overriding
+   *
+   * @param context for event sources
+   * @return event source instance
+   */
   @SuppressWarnings("unchecked")
   public T initEventSource(EventSourceContext<P> context) {
     return (T) eventSource(context).orElseThrow();

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

@@ -31,7 +31,13 @@ default Optional<String> eventSourceName() {
    */
   Class<S> stateResourceClass();
 
-  /** State resource which contains the target state. Usually an ID to address the resource */
+  /**
+   * State resource which contains the target state. Usually an ID to address the resource
+   *
+   * @param primary resource
+   * @param resource secondary resource
+   * @return that stores state
+   */
   S stateResource(P primary, R resource);
 
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/dependent/kubernetes/GenericKubernetesResourceMatcher.java

@@ -124,6 +124,7 @@ public static <R extends HasMetadata> Result<R> match(R desired, R actualResourc
    * @param <R> the type of resource we want to determine whether they match or not
    * @param <P> the type of primary resources associated with the secondary resources we want to
    *        match
+   * @param strongEquality if the resource should match exactly
    */
   public static <R extends HasMetadata, P extends HasMetadata> Result<R> match(
       KubernetesDependentResource<R, P> dependentResource, R actualResource, P primary,

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

@@ -22,6 +22,7 @@ public Map<DependentResource, Exception> getErroredDependents() {
 
   /**
    * @deprecated Use {@link #erroredDependentsExist()} instead
+   * @return if any dependents are in error state
    */
   @Deprecated(forRemoval = true)
   public boolean erroredDependentsExists() {

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

@@ -222,6 +222,10 @@ public <R> List<ResourceEventSource<R, P>> getResourceEventSourcesFor(Class<R> d
 
   /**
    * @deprecated Use {@link #getResourceEventSourceFor(Class)} instead
+   *
+   * @param <R> target resource type
+   * @param dependentType target resource class
+   * @return list of related event sources
    */
   @Deprecated
   public <R> List<ResourceEventSource<R, P>> getEventSourcesFor(Class<R> dependentType) {

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/rate/RateLimiter.java

@@ -10,6 +10,7 @@ interface RateLimitState {
   }
 
   /**
+   * @param rateLimitState state implementation
    * @return empty if permission acquired or minimal duration until a permission could be acquired
    *         again
    */

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

@@ -6,6 +6,7 @@
 import io.javaoperatorsdk.operator.processing.event.ResourceID;
 
 /**
+ * <p>
  * 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
@@ -18,16 +19,19 @@
  * 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/>
+ * </p>
+ * <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/>
+ * </p>
+ * <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.
+ * </p>
  *
  * @param <P> primary resource type
  */

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/retry/GenericRetry.java

@@ -21,6 +21,9 @@ public static GenericRetry noRetry() {
 
   /**
    * @deprecated Use the {@link GradualRetry} annotation instead
+   *
+   * @param configuration retry config
+   * @return Retry instance
    */
   @Deprecated(forRemoval = true)
   public static Retry fromConfiguration(RetryConfiguration configuration) {