Address JavaDoc warnings (#28)

danielsiwiec · web-flow · commit c2d2e6f9b5b1 · 2021-10-20T14:21:14.000-07:00
Signed-off-by: Dan Siwiec &lt;daniel.siwiec@gmail.com&gt;
diff --git a/common-test/src/main/java/feast/common/it/BaseIT.java b/common-test/src/main/java/feast/common/it/BaseIT.java
@@ -115,7 +115,7 @@ public ConsumerFactory<String, byte[]> testConsumerFactory() {
   /**
    * Truncates all tables in Database (between tests or flows). Retries on deadlock
    *
-   * @throws SQLException
+   * @throws SQLException when a SQL exception occurs
    */
   public static void cleanTables() throws SQLException {
     Connection connection =
@@ -156,7 +156,12 @@ public static void cleanTables() throws SQLException {
     }
   }
 
-  /** Used to determine SequentialFlows */
+  /**
+   * Used to determine SequentialFlows
+   *
+   * @param testInfo test info
+   * @return true if test is sequential
+   */
   public Boolean isSequentialTest(TestInfo testInfo) {
     try {
       testInfo.getTestClass().get().asSubclass(SequentialFlow.class);
diff --git a/common-test/src/main/java/feast/common/util/TestUtil.java b/common-test/src/main/java/feast/common/util/TestUtil.java
@@ -44,6 +44,10 @@ public static void setupAuditLogger() {
 
   /**
    * Compare if two Feature Table specs are equal. Disregards order of features/entities in spec.
+   *
+   * @param spec one spec
+   * @param otherSpec the other spec
+   * @return true if specs equal
    */
   public static boolean compareFeatureTableSpec(FeatureTableSpec spec, FeatureTableSpec otherSpec) {
     spec =
diff --git a/common/src/main/java/feast/common/auth/credentials/GoogleAuthCredentials.java b/common/src/main/java/feast/common/auth/credentials/GoogleAuthCredentials.java
@@ -45,6 +45,7 @@ public class GoogleAuthCredentials extends CallCredentials {
    *
    * @param options a map of options, Required unless specified: audience - Optional, Sets the
    *     target audience of the token obtained.
+   * @throws IOException if credentials are not available
    */
   public GoogleAuthCredentials(Map<String, String> options) throws IOException {
     String targetAudience = options.getOrDefault("audience", "https://localhost");
diff --git a/common/src/main/java/feast/common/logging/AuditLogger.java b/common/src/main/java/feast/common/logging/AuditLogger.java
@@ -65,6 +65,7 @@ public AuditLogger(LoggingProperties loggingProperties, BuildProperties buildPro
   /**
    * Log the handling of a Protobuf message by a service call.
    *
+   * @param level log level
    * @param entryBuilder with all fields set except instance.
    */
   public static void logMessage(Level level, MessageAuditLogEntry.Builder entryBuilder) {
diff --git a/common/src/main/java/feast/common/logging/entry/ActionAuditLogEntry.java b/common/src/main/java/feast/common/logging/entry/ActionAuditLogEntry.java
@@ -21,10 +21,10 @@
 /** ActionAuditLogEntry records an action being taken on a specific resource */
 @AutoValue
 public abstract class ActionAuditLogEntry extends AuditLogEntry {
-  /** The name of the action taken on the resource. */
+  /** @return The name of the action taken on the resource. */
   public abstract String getAction();
 
-  /** The target resource of which the action was taken on. */
+  /** @return The target resource of which the action was taken on. */
   public abstract LogResource getResource();
 
   /**
@@ -34,6 +34,7 @@ public abstract class ActionAuditLogEntry extends AuditLogEntry {
    * @param version The version of Feast producing this {@link AuditLogEntry}.
    * @param resource The target resource of which the action was taken on.
    * @param action The name of the action being taken on the given resource.
+   * @return log entry that records an action being taken on a specific resource
    */
   public static ActionAuditLogEntry of(
       String component, String version, LogResource resource, String action) {
diff --git a/common/src/main/java/feast/common/logging/entry/AuditLogEntry.java b/common/src/main/java/feast/common/logging/entry/AuditLogEntry.java
@@ -29,15 +29,27 @@ public abstract class AuditLogEntry {
 
   public final String application = "Feast";
 
-  /** The name of the Feast component producing this {@link AuditLogEntry} */
+  /**
+   * The name of the Feast component producing this {@link AuditLogEntry}
+   *
+   * @return the component
+   */
   public abstract String getComponent();
 
-  /** The version of Feast producing this {@link AuditLogEntry} */
+  /**
+   * The version of Feast producing this {@link AuditLogEntry}
+   *
+   * @return version
+   */
   public abstract String getVersion();
 
   public abstract AuditLogEntryKind getKind();
 
-  /** Return a structured JSON representation of this {@link AuditLogEntry} */
+  /**
+   * Return a structured JSON representation of this {@link AuditLogEntry}
+   *
+   * @return structured JSON representation
+   */
   public String toJSON() {
     Gson gson = new Gson();
     return gson.toJson(this);
diff --git a/common/src/main/java/feast/common/logging/entry/MessageAuditLogEntry.java b/common/src/main/java/feast/common/logging/entry/MessageAuditLogEntry.java
@@ -34,32 +34,35 @@
 /** MessageAuditLogEntry records the handling of a Protobuf message by a service call. */
 @AutoValue
 public abstract class MessageAuditLogEntry extends AuditLogEntry {
-  /** Id used to identify the service call that the log entry is recording */
+  /** @return Id used to identify the service call that the log entry is recording */
   public abstract UUID getId();
 
-  /** The name of the service that was used to handle the service call. */
+  /** @return The name of the service that was used to handle the service call. */
   public abstract String getService();
 
-  /** The name of the method that was used to handle the service call. */
+  /** @return The name of the method that was used to handle the service call. */
   public abstract String getMethod();
 
-  /** The request Protobuf {@link Message} that was passed to the Service in the service call. */
+  /**
+   * @return The request Protobuf {@link Message} that was passed to the Service in the service
+   *     call.
+   */
   public abstract Message getRequest();
 
   /**
-   * The response Protobuf {@link Message} that was passed to the Service in the service call. May
-   * be an {@link Empty} protobuf no request could be collected due to an error.
+   * @return The response Protobuf {@link Message} that was passed to the Service in the service
+   *     call. May be an {@link Empty} protobuf no request could be collected due to an error.
    */
   public abstract Message getResponse();
 
   /**
-   * The authenticated identity that was assumed during the handling of the service call. For
-   * example, the user id or email that identifies the user making the call. Empty if the service
-   * call is not authenticated.
+   * @return The authenticated identity that was assumed during the handling of the service call.
+   *     For example, the user id or email that identifies the user making the call. Empty if the
+   *     service call is not authenticated.
    */
   public abstract String getIdentity();
 
-  /** The result status code of the service call. */
+  /** @return The result status code of the service call. */
   public abstract Code getStatusCode();
 
   @AutoValue.Builder
diff --git a/common/src/main/java/feast/common/logging/entry/TransitionAuditLogEntry.java b/common/src/main/java/feast/common/logging/entry/TransitionAuditLogEntry.java
@@ -21,10 +21,10 @@
 /** TransitionAuditLogEntry records a transition in state/status in a specific resource. */
 @AutoValue
 public abstract class TransitionAuditLogEntry extends AuditLogEntry {
-  /** The resource which the state/status transition occured. */
+  /** @return The resource which the state/status transition occured. */
   public abstract LogResource getResource();
 
-  /** The end status with the resource transition to. */
+  /** @return The end status with the resource transition to. */
   public abstract String getStatus();
 
   /**
@@ -35,6 +35,7 @@ public abstract class TransitionAuditLogEntry extends AuditLogEntry {
    * @param version The version of Feast producing this {@link AuditLogEntry}.
    * @param resource the resource which the transtion occured
    * @param status the end status which the resource transitioned to.
+   * @return log entry to record a transition in state/status in a specific resource
    */
   public static TransitionAuditLogEntry of(
       String component, String version, LogResource resource, String status) {
diff --git a/common/src/main/java/feast/common/models/FeatureTable.java b/common/src/main/java/feast/common/models/FeatureTable.java
@@ -25,6 +25,7 @@ public class FeatureTable {
    * Accepts FeatureTableSpec object and returns its reference in String
    * "project/featuretable_name".
    *
+   * @param project project name
    * @param featureTableSpec {@link FeatureTableSpec}
    * @return String format of FeatureTableReference
    */
@@ -36,6 +37,7 @@ public static String getFeatureTableStringRef(String project, FeatureTableSpec f
    * Accepts FeatureReferenceV2 object and returns its reference in String
    * "project/featuretable_name".
    *
+   * @param project project name
    * @param featureReference {@link FeatureReferenceV2}
    * @return String format of FeatureTableReference
    */
diff --git a/common/src/main/java/feast/common/validators/OneOfStringValidator.java b/common/src/main/java/feast/common/validators/OneOfStringValidator.java
@@ -29,7 +29,7 @@ public class OneOfStringValidator implements ConstraintValidator<OneOfStrings, S
   /**
    * Initialize the OneOfStringValidator with a collection of allowed String values.
    *
-   * @param constraintAnnotation
+   * @param constraintAnnotation constraint annotation
    */
   @Override
   public void initialize(OneOfStrings constraintAnnotation) {
diff --git a/common/src/main/java/feast/common/validators/OneOfStrings.java b/common/src/main/java/feast/common/validators/OneOfStrings.java
@@ -38,10 +38,12 @@
   /** @return Default error message that is returned if the incorrect value is set */
   String message() default "Field value must be one of the following: {value}";
 
-  /** Allows for the specification of validation groups to which this constraint belongs. */
+  /** @return Allows for the specification of validation groups to which this constraint belongs. */
   Class<?>[] groups() default {};
 
-  /** An attribute payload that can be used to assign custom payload objects to a constraint. */
+  /**
+   * @return An attribute payload that can be used to assign custom payload objects to a constraint.
+   */
   Class<? extends Payload>[] payload() default {};
 
   /** @return Default value that is returned if no allowed values are configured */
diff --git a/core/src/main/java/feast/core/config/WebSecurityConfig.java b/core/src/main/java/feast/core/config/WebSecurityConfig.java
@@ -43,7 +43,7 @@ public WebSecurityConfig(FeastProperties feastProperties) {
    * Allows for custom web security rules to be applied.
    *
    * @param http {@link HttpSecurity} for configuring web based security
-   * @throws Exception
+   * @throws Exception unexpected exception
    */
   @Override
   protected void configure(HttpSecurity http) throws Exception {
diff --git a/core/src/main/java/feast/core/model/DataSource.java b/core/src/main/java/feast/core/model/DataSource.java
@@ -87,6 +87,7 @@ public DataSource(SourceType type) {
    * @param spec Protobuf representation of DataSource to construct from.
    * @throws IllegalArgumentException when provided with a invalid Protobuf spec
    * @throws UnsupportedOperationException if source type is unsupported.
+   * @return data source
    */
   public static DataSource fromProto(DataSourceProto.DataSource spec) {
     DataSource source = new DataSource(spec.getType());
@@ -132,7 +133,11 @@ public static DataSource fromProto(DataSourceProto.DataSource spec) {
     return source;
   }
 
-  /** Convert this DataSource to its Protobuf representation. */
+  /**
+   * Convert this DataSource to its Protobuf representation.
+   *
+   * @return protobuf representation
+   */
   public DataSourceProto.DataSource toProto() {
     DataSourceProto.DataSource.Builder spec = DataSourceProto.DataSource.newBuilder();
     spec.setType(getType());
diff --git a/core/src/main/java/feast/core/model/EntityV2.java b/core/src/main/java/feast/core/model/EntityV2.java
@@ -65,6 +65,11 @@ public EntityV2() {
    *
    * <p>This data model supports Scalar Entity and would allow ease of discovery of entities and
    * reasoning when used in association with FeatureTable.
+   *
+   * @param name name
+   * @param description description
+   * @param type type
+   * @param labels labels
    */
   public EntityV2(
       String name, String description, ValueType.Enum type, Map<String, String> labels) {
diff --git a/core/src/main/java/feast/core/model/FeatureTable.java b/core/src/main/java/feast/core/model/FeatureTable.java
@@ -155,7 +155,9 @@ public static FeatureTable fromProto(
   /**
    * Update the FeatureTable from the given Protobuf representation.
    *
+   * @param projectName project name
    * @param spec the Protobuf spec to update the FeatureTable from.
+   * @param entityRepo repository
    * @throws IllegalArgumentException if the update will make prohibited changes.
    */
   public void updateFromProto(
@@ -211,7 +213,11 @@ public void updateFromProto(
     this.revision++;
   }
 
-  /** Convert this Feature Table to its Protobuf representation */
+  /**
+   * Convert this Feature Table to its Protobuf representation
+   *
+   * @return protobuf representation
+   */
   public FeatureTableProto.FeatureTable toProto() {
     // Convert field types to Protobuf compatible types
     Timestamp creationTime = TypeConversion.convertTimestamp(getCreated());
@@ -319,6 +325,7 @@ private Map<String, FeatureV2> getFeaturesRefToFeaturesMap(List<FeatureV2> featu
   /**
    * Returns a list of Features if FeatureTable's Feature contains all labels in labelsFilter
    *
+   * @param features features
    * @param labelsFilter contain labels that should be attached to FeatureTable's features
    * @return List of Features
    */
diff --git a/core/src/main/java/feast/core/model/FeatureV2.java b/core/src/main/java/feast/core/model/FeatureV2.java
@@ -75,7 +75,11 @@ public static FeatureV2 fromProto(FeatureTable table, FeatureSpecV2 spec) {
     return new FeatureV2(table, spec.getName(), spec.getValueType(), labelsJSON);
   }
 
-  /** Convert this Feature to its Protobuf representation. */
+  /**
+   * Convert this Feature to its Protobuf representation.
+   *
+   * @return protobuf representation
+   */
   public FeatureSpecV2 toProto() {
     Map<String, String> labels = TypeConversion.convertJsonStringToMap(getLabelsJSON());
     return FeatureSpecV2.newBuilder()
diff --git a/core/src/main/java/feast/core/service/SpecService.java b/core/src/main/java/feast/core/service/SpecService.java
@@ -262,6 +262,7 @@ public ListStoresResponse listStores(ListStoresRequest.Filter filter) {
    *
    * @param newEntitySpec EntitySpecV2 that will be used to create or update an Entity.
    * @param projectName Project namespace of Entity which is to be created/updated
+   * @return response of the operation
    */
   @Transactional
   public ApplyEntityResponse applyEntity(
@@ -314,6 +315,7 @@ public ApplyEntityResponse applyEntity(
    * Resolves the project name by returning name if given, autofilling default project otherwise.
    *
    * @param projectName name of the project to resolve.
+   * @return project name
    */
   public static String resolveProjectName(String projectName) {
     return (projectName.isEmpty()) ? Project.DEFAULT_NAME : projectName;
@@ -324,6 +326,7 @@ public static String resolveProjectName(String projectName) {
    *
    * @param updateStoreRequest containing the new store definition
    * @return UpdateStoreResponse containing the new store definition
+   * @throws InvalidProtocolBufferException if protobuf exception occurs
    */
   @Transactional
   public UpdateStoreResponse updateStore(UpdateStoreRequest updateStoreRequest)
diff --git a/core/src/main/java/feast/core/util/TypeConversion.java b/core/src/main/java/feast/core/util/TypeConversion.java
@@ -79,7 +79,7 @@ public static Map<String, Enum> convertJsonStringToEnumMap(String jsonString) {
   /**
    * Marshals a given map into its corresponding json string
    *
-   * @param map
+   * @param map map to be converted
    * @return json string corresponding to given map
    */
   public static String convertMapToJsonString(Map<String, String> map) {
@@ -89,7 +89,7 @@ public static String convertMapToJsonString(Map<String, String> map) {
   /**
    * Marshals a given Enum map into its corresponding json string
    *
-   * @param map
+   * @param map map to be converted
    * @return json string corresponding to given Enum map
    */
   public static String convertEnumMapToJsonString(Map<String, Enum> map) {
diff --git a/core/src/main/java/feast/core/validators/DataSourceValidator.java b/core/src/main/java/feast/core/validators/DataSourceValidator.java
@@ -24,7 +24,11 @@
 import feast.proto.core.DataSourceProto.DataSource;
 
 public class DataSourceValidator {
-  /** Validate if the given DataSource protobuf spec is valid. */
+  /**
+   * Validate if the given DataSource protobuf spec is valid.
+   *
+   * @param spec spec to be validated
+   */
   public static void validate(DataSource spec) {
     switch (spec.getType()) {
       case BATCH_FILE:
diff --git a/pom.xml b/pom.xml
@@ -543,6 +543,9 @@
                         </goals>
                     </execution>
                 </executions>
+                <configuration>
+                    <excludePackageNames>feast.proto.*:io.grpc.*:org.tensorflow.*</excludePackageNames>
+                </configuration>
             </plugin>
             <plugin>
                 <groupId>com.diffplug.spotless</groupId>
diff --git a/sdk/java/src/main/java/com/gojek/feast/SecurityConfig.java b/sdk/java/src/main/java/com/gojek/feast/SecurityConfig.java
@@ -26,15 +26,23 @@ public abstract class SecurityConfig {
   /**
    * Enables authentication If specified, the call credentials used to provide credentials to
    * authenticate with Feast.
+   *
+   * @return credentials
    */
   public abstract Optional<CallCredentials> getCredentials();
 
-  /** Whether to use TLS transport security is use when connecting to Feast. */
+  /**
+   * Whether to use TLS transport security is use when connecting to Feast.
+   *
+   * @return true if enabled
+   */
   public abstract boolean isTLSEnabled();
 
   /**
    * If specified and TLS is enabled, provides path to TLS certificate use the verify Service
    * identity.
+   *
+   * @return certificate path
    */
   public abstract Optional<String> getCertificatePath();
 
diff --git a/serving/src/main/java/feast/serving/config/FeastProperties.java b/serving/src/main/java/feast/serving/config/FeastProperties.java
@@ -381,7 +381,11 @@ public LoggingProperties getLogging() {
     return logging;
   }
 
-  /** Sets logging properties @@param logging the logging properties */
+  /**
+   * Sets logging properties
+   *
+   * @param logging the logging properties
+   */
   public void setLogging(LoggingProperties logging) {
     this.logging = logging;
   }
diff --git a/serving/src/main/java/feast/serving/config/WebSecurityConfig.java b/serving/src/main/java/feast/serving/config/WebSecurityConfig.java
diff --git a/storage/api/src/main/java/feast/storage/api/retriever/OnlineRetrieverV2.java b/storage/api/src/main/java/feast/storage/api/retriever/OnlineRetrieverV2.java
diff --git a/storage/connectors/redis/src/main/java/feast/storage/connectors/redis/common/RedisHashDecoder.java b/storage/connectors/redis/src/main/java/feast/storage/connectors/redis/common/RedisHashDecoder.java

Original file line number	Diff line number	Diff line change
`@@ -45,6 +45,7 @@ public class GoogleAuthCredentials extends CallCredentials {`
`45`	`45`	`*`
`46`	`46`	`* @param options a map of options, Required unless specified: audience - Optional, Sets the`
`47`	`47`	`* target audience of the token obtained.`
	`48`	`+ * @throws IOException if credentials are not available`
`48`	`49`	`*/`
`49`	`50`	`public GoogleAuthCredentials(Map<String, String> options) throws IOException {`
`50`	`51`	`String targetAudience = options.getOrDefault("audience", "https://localhost");`
Original file line number	Diff line number	Diff line change
`@@ -65,6 +65,7 @@ public AuditLogger(LoggingProperties loggingProperties, BuildProperties buildPro`
`65`	`65`	`/**`
`66`	`66`	`* Log the handling of a Protobuf message by a service call.`
`67`	`67`	`*`
	`68`	`+ * @param level log level`
`68`	`69`	`* @param entryBuilder with all fields set except instance.`
`69`	`70`	`*/`
`70`	`71`	`public static void logMessage(Level level, MessageAuditLogEntry.Builder entryBuilder) {`
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,7 @@ public class OneOfStringValidator implements ConstraintValidator<OneOfStrings, S`
`29`	`29`	`/**`
`30`	`30`	`* Initialize the OneOfStringValidator with a collection of allowed String values.`
`31`	`31`	`*`
`32`		`- * @param constraintAnnotation`
	`32`	`+ * @param constraintAnnotation constraint annotation`
`33`	`33`	`*/`
`34`	`34`	`@Override`
`35`	`35`	`public void initialize(OneOfStrings constraintAnnotation) {`