fix: clean up all javadoc warnings

core-api/src/main/java/com/optimizely/ab/Optimizely.java

@@ -1354,34 +1354,51 @@ public NotificationCenter getNotificationCenter() {
 
     /**
      * Convenience method for adding DecisionNotification Handlers
+     *
+     * @param handler DicisionNotification handler
+     * @return A handler Id (greater than 0 if succeeded)
      */
     public int addDecisionNotificationHandler(NotificationHandler<DecisionNotification> handler) {
         return addNotificationHandler(DecisionNotification.class, handler);
     }
 
     /**
      * Convenience method for adding TrackNotification Handlers
+     *
+     * @param handler TrackNotification handler
+     * @return A handler Id (greater than 0 if succeeded)
      */
     public int addTrackNotificationHandler(NotificationHandler<TrackNotification> handler) {
         return addNotificationHandler(TrackNotification.class, handler);
     }
 
     /**
      * Convenience method for adding UpdateConfigNotification Handlers
+     *
+     * @param handler UpdateConfigNotification handler
+     * @return A handler Id (greater than 0 if succeeded)
      */
     public int addUpdateConfigNotificationHandler(NotificationHandler<UpdateConfigNotification> handler) {
         return addNotificationHandler(UpdateConfigNotification.class, handler);
     }
 
     /**
      * Convenience method for adding LogEvent Notification Handlers
+     *
+     * @param handler NotificationHandler handler
+     * @return A handler Id (greater than 0 if succeeded)
      */
     public int addLogEventNotificationHandler(NotificationHandler<LogEvent> handler) {
         return addNotificationHandler(LogEvent.class, handler);
     }
 
     /**
      * Convenience method for adding NotificationHandlers
+     *
+     * @param clazz The class of NotificationHandler
+     * @param handler NotificationHandler handler
+     * @param <T> This is the type parameter
+     * @return A handler Id (greater than 0 if succeeded)
      */
     public <T> int addNotificationHandler(Class<T> clazz, NotificationHandler<T> handler) {
         return notificationCenter.addNotificationHandler(clazz, handler);
@@ -1403,6 +1420,10 @@ public <T> int addNotificationHandler(Class<T> clazz, NotificationHandler<T> han
      *         .withEventHandler(eventHandler)
      *         .build();
      * </pre>
+     *
+     * @param datafile  A datafile
+     * @param eventHandler An EventHandler
+     * @return An Optimizely builder
      */
     @Deprecated
     public static Builder builder(@Nonnull String datafile,
@@ -1460,6 +1481,9 @@ public Builder withErrorHandler(ErrorHandler errorHandler) {
          * method.
          * {@link com.optimizely.ab.event.BatchEventProcessor.Builder#withEventHandler(com.optimizely.ab.event.EventHandler)}  label}
          * Please use that builder method instead.
+         *
+         * @param eventHandler An EventHandler
+         * @return An Optimizely builder
          */
         @Deprecated
         public Builder withEventHandler(EventHandler eventHandler) {
@@ -1469,6 +1493,9 @@ public Builder withEventHandler(EventHandler eventHandler) {
 
         /**
          * You can instantiate a BatchEventProcessor or a ForwardingEventProcessor or supply your own.
+         *
+         * @param eventProcessor An EventProcessor
+         * @return An Optimizely builder
          */
         public Builder withEventProcessor(EventProcessor eventProcessor) {
             this.eventProcessor = eventProcessor;

core-api/src/main/java/com/optimizely/ab/OptimizelyUserContext.java

@@ -155,7 +155,7 @@ public Map<String, OptimizelyDecision> decideAll() {
      *
      * @param eventName The event name.
      * @param eventTags A map of event tag names to event tag values.
-     * @throws UnknownEventTypeException
+     * @throws UnknownEventTypeException when event type is unknown
      */
     public void trackEvent(@Nonnull String eventName,
                            @Nonnull Map<String, ?> eventTags) throws UnknownEventTypeException {
@@ -166,7 +166,7 @@ public void trackEvent(@Nonnull String eventName,
      * Track an event.
      *
      * @param eventName The event name.
-     * @throws UnknownEventTypeException
+     * @throws UnknownEventTypeException when event type is unknown
      */
     public void trackEvent(@Nonnull String eventName) throws UnknownEventTypeException {
         trackEvent(eventName, Collections.emptyMap());

core-api/src/main/java/com/optimizely/ab/config/DatafileProjectConfig.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2016-2020, Optimizely and contributors
+ *    Copyright 2016-2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -278,7 +278,7 @@ private List<Experiment> aggregateGroupExperiments(List<Group> groups) {
     /**
      * Checks is attributeKey is reserved or not and if it exist in attributeKeyMapping
      *
-     * @param attributeKey
+     * @param attributeKey The attribute key
      * @return AttributeId corresponding to AttributeKeyMapping, AttributeKey when it's a reserved attribute and
      * null when attributeKey is equal to BOT_FILTERING_ATTRIBUTE key.
      */
@@ -484,6 +484,7 @@ public Builder withDatafile(String datafile) {
 
         /**
          * @return a {@link DatafileProjectConfig} instance given a JSON string datafile
+         * @throws ConfigParseException when parsing datafile fails
          */
         public ProjectConfig build() throws ConfigParseException {
             if (datafile == null) {

core-api/src/main/java/com/optimizely/ab/config/ProjectConfigUtils.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2016-2017, 2019, Optimizely and contributors
+ *    Copyright 2016-2017,2019,2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -26,6 +26,10 @@ public class ProjectConfigUtils {
 
     /**
      * Helper method for creating convenience mappings from key to entity
+     *
+     * @param nameables The list of IdMapped entities
+     * @param <T> This is the type parameter
+     * @return The map of key to entity
      */
     public static <T extends IdKeyMapped> Map<String, T> generateNameMapping(List<T> nameables) {
         Map<String, T> nameMapping = new HashMap<String, T>();
@@ -38,6 +42,10 @@ public static <T extends IdKeyMapped> Map<String, T> generateNameMapping(List<T>
 
     /**
      * Helper method for creating convenience mappings from ID to entity
+     *
+     * @param nameables The list of IdMapped entities
+     * @param <T> This is the type parameter
+     * @return The map of ID to entity
      */
     public static <T extends IdMapped> Map<String, T> generateIdMapping(List<T> nameables) {
         Map<String, T> nameMapping = new HashMap<String, T>();
@@ -50,6 +58,9 @@ public static <T extends IdMapped> Map<String, T> generateIdMapping(List<T> name
 
     /**
      * Helper method for creating convenience mappings of ExperimentID to featureFlags it is included in.
+     *
+     * @param featureFlags The list of feture flags
+     * @return The mapping of ExperimentID to featureFlags
      */
     public static Map<String, List<String>> generateExperimentFeatureMapping(List<FeatureFlag> featureFlags) {
         Map<String, List<String>> experimentFeatureMap = new HashMap<>();

core-api/src/main/java/com/optimizely/ab/config/audience/AudienceIdCondition.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2018-2020, Optimizely and contributors
+ *    Copyright 2018-2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -45,7 +45,7 @@ public class AudienceIdCondition<T> implements Condition<T> {
     /**
      * Constructor used in json parsing to store the audienceId parsed from Experiment.audienceConditions.
      *
-     * @param audienceId
+     * @param audienceId The audience id
      */
     @JsonCreator
     public AudienceIdCondition(String audienceId) {

core-api/src/main/java/com/optimizely/ab/config/audience/match/MatchRegistry.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2020, Optimizely and contributors
+ *    Copyright 2020-2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -72,8 +72,8 @@ public static Match getMatch(String name) throws UnknownMatchTypeException {
      * register registers a Match implementation with it's name.
      * NOTE: This does not check for existence so default implementations can
      * be overridden.
-     * @param name
-     * @param match
+     * @param name  The match name
+     * @param match The match implementation
      */
     public static void register(String name, Match match) {
         registry.put(name, match);

core-api/src/main/java/com/optimizely/ab/config/audience/match/SemanticVersion.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2020, Optimizely and contributors
+ *    Copyright 2020-2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -44,6 +44,11 @@ public SemanticVersion(String version) {
     /**
      * compare takes object inputs and coerces them into SemanticVersion objects before performing the comparison.
      * If the input values cannot be coerced then an {@link UnexpectedValueTypeException} is thrown.
+     *
+     * @param o1    The object to be compared
+     * @param o2    The object to be compared to
+     * @return The compare result
+     * @throws UnexpectedValueTypeException when an error is detected while comparing
      */
     public static int compare(Object o1, Object o2) throws UnexpectedValueTypeException {
         if (o1 instanceof String && o2 instanceof String) {

core-api/src/main/java/com/optimizely/ab/config/parser/ConfigParser.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2016-2017, Optimizely and contributors
+ *    Copyright 2016-2017,2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -33,14 +33,18 @@
 public interface ConfigParser {
 
     /**
-     * @param json the json to parse
-     * @return generates a {@code ProjectConfig} configuration from the provided json
+     * @param json The json to parse
+     * @return The {@code ProjectConfig} configuration from the provided json
      * @throws ConfigParseException when there's an issue parsing the provided project config
      */
     ProjectConfig parseProjectConfig(@Nonnull String json) throws ConfigParseException;
 
     /**
      * OptimizelyJSON parsing
+     *
+     * @param src The OptimizelyJSON
+     * @return The serialized String
+     * @throws JsonParseException when parsing JSON fails
      */
     String toJson(Object src) throws JsonParseException;
     <T> T fromJson(String json, Class<T> clazz) throws JsonParseException;

core-api/src/main/java/com/optimizely/ab/event/BatchEventProcessor.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2019, Optimizely and contributors
+ *    Copyright 2019,2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -246,6 +246,9 @@ public static class Builder {
 
         /**
          * {@link EventHandler} implementation used to dispatch events to Optimizely.
+         *
+         * @param eventHandler The event handler
+         * @return The BatchEventProcessor builder
          */
         public Builder withEventHandler(EventHandler eventHandler) {
             this.eventHandler = eventHandler;
@@ -254,6 +257,9 @@ public Builder withEventHandler(EventHandler eventHandler) {
 
         /**
          * EventQueue is the underlying BlockingQueue used to buffer events before being added to the batch payload.
+         *
+         * @param eventQueue The event queue
+         * @return The BatchEventProcessor builder
          */
         public Builder withEventQueue(BlockingQueue<Object> eventQueue) {
             this.eventQueue = eventQueue;
@@ -262,6 +268,9 @@ public Builder withEventQueue(BlockingQueue<Object> eventQueue) {
 
         /**
          * BatchSize is the maximum number of events contained within a single event batch.
+         *
+         * @param batchSize The batch size
+         * @return The BatchEventProcessor builder
          */
         public Builder withBatchSize(Integer batchSize) {
             this.batchSize = batchSize;
@@ -271,6 +280,9 @@ public Builder withBatchSize(Integer batchSize) {
         /**
          * FlushInterval is the maximum duration, in milliseconds, that an event will remain in flight before
          * being flushed to the event dispatcher.
+         *
+         * @param flushInterval The flush interval
+         * @return The BatchEventProcessor builder
          */
         public Builder withFlushInterval(Long flushInterval) {
             this.flushInterval = flushInterval;
@@ -279,6 +291,9 @@ public Builder withFlushInterval(Long flushInterval) {
 
         /**
          * ExecutorService used to execute the {@link EventConsumer} thread.
+         *
+         * @param executor The ExecutorService
+         * @return The BatchEventProcessor builder
          */
         public Builder withExecutor(ExecutorService executor) {
             this.executor = executor;
@@ -287,6 +302,10 @@ public Builder withExecutor(ExecutorService executor) {
 
         /**
          * Timeout is the maximum time to wait for the EventProcessor to close.
+         *
+         * @param duration The max time to wait for the EventProcessor to close
+         * @param timeUnit The time unit
+         * @return The BatchEventProcessor builder
          */
         public Builder withTimeout(long duration, TimeUnit timeUnit) {
             this.timeoutMillis = timeUnit.toMillis(duration);
@@ -295,6 +314,9 @@ public Builder withTimeout(long duration, TimeUnit timeUnit) {
 
         /**
          * NotificationCenter used to notify when event batches are flushed.
+         *
+         * @param notificationCenter The NotificationCenter
+         * @return The BatchEventProcessor builder
          */
         public Builder withNotificationCenter(NotificationCenter notificationCenter) {
             this.notificationCenter = notificationCenter;

core-api/src/main/java/com/optimizely/ab/internal/ConditionUtils.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2018-2019, Optimizely and contributors
+ *    Copyright 2018-2019,2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -122,7 +122,9 @@ static public <T> Condition parseConditions(Class<T> clazz, Object object) throw
     /**
      * parse conditions using List and Map
      *
+     * @param clazz the class of parsed condition
      * @param rawObjectList list of conditions
+     * @param <T> This is the type parameter
      * @return audienceCondition
      */
     static public <T> Condition parseConditions(Class<T> clazz, List<Object> rawObjectList) throws InvalidAudienceCondition {
@@ -183,7 +185,9 @@ static public String operand(Object object) {
     /**
      * Parse conditions from org.json.JsonArray
      *
+     * @param clazz the class of parsed condition
      * @param conditionJson jsonArray to parse
+     * @param <T> This is the type parameter
      * @return condition parsed from conditionJson.
      */
     static public <T> Condition parseConditions(Class<T> clazz, org.json.JSONArray conditionJson) throws InvalidAudienceCondition {

core-api/src/main/java/com/optimizely/ab/internal/EventTagUtils.java

@@ -1,6 +1,6 @@
 /**
  *
- *    Copyright 2016-2019, Optimizely and contributors
+ *    Copyright 2016-2019,2021, Optimizely and contributors
  *
  *    Licensed under the Apache License, Version 2.0 (the "License");
  *    you may not use this file except in compliance with the License.
@@ -29,8 +29,8 @@ public final class EventTagUtils {
     /**
      * Grab the revenue value from the event tags. "revenue" is a reserved keyword.
      *
-     * @param eventTags
-     * @return Long
+     * @param eventTags The event tags
+     * @return Long     The revenue value
      */
     public static Long getRevenueValue(@Nonnull Map<String, ?> eventTags) {
         Long eventValue = null;
@@ -51,6 +51,9 @@ public static Long getRevenueValue(@Nonnull Map<String, ?> eventTags) {
 
     /**
      * Fetch the numeric metric value from event tags. "value" is a reserved keyword.
+     *
+     * @param eventTags  The event tags
+     * @return  The numeric metric value
      */
     public static Double getNumericValue(@Nonnull Map<String, ?> eventTags) {
         Double eventValue = null;