fix: clean up all javadoc warnings (#426)

Author: jaeopt

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 {