SNOW-1016469: Adding missing comments to public methods (#1928)

src/main/java/net/snowflake/client/config/SFClientConfigParser.java

@@ -33,6 +33,7 @@ public class SFClientConfigParser {
    * @param configFilePath SF_CLIENT_CONFIG_FILE parameter read from connection URL or connection
    *     properties
    * @return SFClientConfig
+   * @throws IOException if exception encountered when reading config file.
    */
   public static SFClientConfig loadSFClientConfig(String configFilePath) throws IOException {
     if (configFilePath != null) {

src/main/java/net/snowflake/client/core/ChunkDownloader.java

@@ -14,13 +14,16 @@ public interface ChunkDownloader {
    * be blocked if the chunk is not ready to be consumed (a.k.a not loaded into memory yet)
    *
    * @return result chunk with data loaded
+   * @throws InterruptedException if downloading thread was interrupted
+   * @throws SnowflakeSQLException if downloader encountered an error
    */
   SnowflakeResultChunk getNextChunkToConsume() throws InterruptedException, SnowflakeSQLException;
 
   /**
    * Terminate the chunk downloader, release all resources allocated
    *
    * @return metrics measuring downloader performance
+   * @throws InterruptedException if error encountered
    */
   DownloaderMetrics terminate() throws InterruptedException;
 }

src/main/java/net/snowflake/client/core/CredentialManager.java

@@ -47,7 +47,7 @@ void resetSecureStorageManager() {
   /**
    * Testing purpose. Inject a mock manager.
    *
-   * @param manager
+   * @param manager SecureStorageManager
    */
   void injectSecureStorageManager(SecureStorageManager manager) {
     logger.debug("Injecting secure storage manager");

src/main/java/net/snowflake/client/core/DataConversionContext.java

@@ -12,25 +12,42 @@
  * to a single result set. a.k.a each result set object should have its own formatter info
  */
 public interface DataConversionContext {
-  /** timestamp_ltz formatter */
+  /**
+   * @return timestamp_ltz formatter
+   */
   SnowflakeDateTimeFormat getTimestampLTZFormatter();
 
-  /** timestamp_ntz formatter */
+  /**
+   * @return timestamp_ntz formatter
+   */
   SnowflakeDateTimeFormat getTimestampNTZFormatter();
 
-  /** timestamp_tz formatter */
+  /**
+   * @return timestamp_ntz formatter
+   */
   SnowflakeDateTimeFormat getTimestampTZFormatter();
 
-  /** date formatter */
+  /**
+   * @return date formatter
+   */
   SnowflakeDateTimeFormat getDateFormatter();
 
-  /** time formatter */
+  /**
+   * @return time formatter
+   */
   SnowflakeDateTimeFormat getTimeFormatter();
 
-  /** binary formatter */
+  /**
+   * @return binary formatter
+   */
   SFBinaryFormat getBinaryFormatter();
 
-  /** get scale from Snowflake metadata */
+  /**
+   * get scale from Snowflake metadata
+   *
+   * @param columnIndex column index
+   * @return scale value
+   */
   int getScale(int columnIndex);
 
   /**

src/main/java/net/snowflake/client/core/EventUtil.java

@@ -36,7 +36,7 @@ public class EventUtil {
   /**
    * Junit is not recognizing the system properties for EventTest, so overriding the value here
    *
-   * @param value
+   * @param value string value
    */
   public static void setDumpPathPrefixForTesting(String value) {
     DUMP_PATH_PREFIX = value;

src/main/java/net/snowflake/client/core/HeartbeatBackground.java

@@ -67,6 +67,7 @@ private HeartbeatBackground() {}
    * @param session the session will be added
    * @param masterTokenValidityInSecs time interval for which client need to check validity of
    *     master token with server
+   * @param heartbeatFrequencyInSecs heartbeat frequency in seconds
    */
   protected synchronized void addSession(
       SFSession session, long masterTokenValidityInSecs, int heartbeatFrequencyInSecs) {

src/main/java/net/snowflake/client/core/HttpClientSettingsKey.java

@@ -122,7 +122,11 @@ public String getUserAgentSuffix() {
     return this.userAgentSuffix;
   }
 
-  /** Be careful of using this! Should only be called when password is later masked. */
+  /**
+   * Be careful of using this! Should only be called when password is later masked.
+   *
+   * @return proxy password
+   */
   @SnowflakeJdbcInternalApi
   public String getProxyPassword() {
     return this.proxyPassword;

src/main/java/net/snowflake/client/core/HttpUtil.java

@@ -65,6 +65,7 @@
 import org.apache.http.ssl.SSLInitializationException;
 import org.apache.http.util.EntityUtils;
 
+/** HttpUtil class */
 public class HttpUtil {
   private static final SFLogger logger = SFLoggerFactory.getLogger(HttpUtil.class);
 
@@ -168,7 +169,7 @@ public static void setProxyForS3(HttpClientSettingsKey key, ClientConfiguration
    *
    * @param proxyProperties proxy properties
    * @param clientConfig the configuration needed by S3 to set the proxy
-   * @throws SnowflakeSQLException
+   * @throws SnowflakeSQLException when exception encountered
    * @deprecated Use {@link S3HttpUtil#setSessionlessProxyForS3(Properties, ClientConfiguration)}
    *     instead
    */
@@ -184,7 +185,7 @@ public static void setSessionlessProxyForS3(
    *
    * @param proxyProperties proxy properties
    * @param opContext the configuration needed by Azure to set the proxy
-   * @throws SnowflakeSQLException
+   * @throws SnowflakeSQLException when invalid proxy properties encountered
    */
   public static void setSessionlessProxyForAzure(
       Properties proxyProperties, OperationContext opContext) throws SnowflakeSQLException {
@@ -723,6 +724,7 @@ public static String executeGeneralRequest(
    * @param includeRetryParameters whether to include retry parameters in retried requests
    * @param retryOnHTTP403 whether to retry on HTTP 403 or not
    * @param ocspAndProxyKey OCSP mode and proxy settings for httpclient
+   * @param execTimeData query execution time telemetry data object
    * @return response
    * @throws SnowflakeSQLException if Snowflake error occurs
    * @throws IOException raises if a general IO error occurs

src/main/java/net/snowflake/client/core/PrivateLinkDetector.java

@@ -6,6 +6,9 @@ public class PrivateLinkDetector {
    * We can only tell if private link is enabled for certain hosts when the hostname contains the
    * word 'privatelink' but we don't have a good way of telling if a private link connection is
    * expected for internal stages for example.
+   *
+   * @param host host
+   * @return true if host is considered as privatelink environment
    */
   public static boolean isPrivateLink(String host) {
     return host.toLowerCase().contains(".privatelink.snowflakecomputing.");

src/main/java/net/snowflake/client/core/QueryContextCache.java

@@ -274,6 +274,8 @@ private static QueryContextElement deserializeQueryContextElement(JsonNode node)
    * Deserialize the QueryContext cache from a QueryContextDTO object. This function currently is
    * only used in QueryContextCacheTest.java where we check that after serialization and
    * deserialization, the cache is the same as before.
+   *
+   * @param queryContextDTO QueryContextDTO to deserialize.
    */
   public void deserializeQueryContextDTO(QueryContextDTO queryContextDTO) {
     synchronized (this) {
@@ -335,6 +337,8 @@ private static QueryContextElement deserializeQueryContextElementDTO(
   /**
    * Serialize the QueryContext cache to a QueryContextDTO object, which can be serialized to JSON
    * automatically later.
+   *
+   * @return {@link QueryContextDTO}
    */
   public QueryContextDTO serializeQueryContextDTO() {
     synchronized (this) {

src/main/java/net/snowflake/client/core/QueryStatus.java

@@ -39,6 +39,7 @@ public String getDescription() {
 
   /**
    * @deprecated use {@link net.snowflake.client.jdbc.QueryStatusV2} instead
+   * @return error message
    */
   @Deprecated
   public String getErrorMessage() {
@@ -47,6 +48,7 @@ public String getErrorMessage() {
 
   /**
    * @deprecated use {@link net.snowflake.client.jdbc.QueryStatusV2} instead
+   * @return error code
    */
   @Deprecated
   public int getErrorCode() {
@@ -55,6 +57,7 @@ public int getErrorCode() {
 
   /**
    * @deprecated use {@link net.snowflake.client.jdbc.QueryStatusV2} instead
+   * @param message the error message
    */
   @Deprecated
   public void setErrorMessage(String message) {
@@ -63,12 +66,19 @@ public void setErrorMessage(String message) {
 
   /**
    * @deprecated use {@link net.snowflake.client.jdbc.QueryStatusV2} instead
+   * @param errorCode the error code
    */
   @Deprecated
   public void setErrorCode(int errorCode) {
     this.errorCode = errorCode;
   }
 
+  /**
+   * Check if query is still running.
+   *
+   * @param status QueryStatus
+   * @return true if query is still running
+   */
   public static boolean isStillRunning(QueryStatus status) {
     switch (status.getValue()) {
       case 0: // "RUNNING"
@@ -83,6 +93,12 @@ public static boolean isStillRunning(QueryStatus status) {
     }
   }
 
+  /**
+   * Check if query status is an error
+   *
+   * @param status QueryStatus
+   * @return true if query status is an error status
+   */
   public static boolean isAnError(QueryStatus status) {
     switch (status.getValue()) {
       case 1: // Aborting
@@ -97,6 +113,12 @@ public static boolean isAnError(QueryStatus status) {
     }
   }
 
+  /**
+   * Get the query status from a string description
+   *
+   * @param description the status description
+   * @return QueryStatus
+   */
   public static QueryStatus getStatusFromString(String description) {
     if (description != null) {
       for (QueryStatus st : QueryStatus.values()) {

src/main/java/net/snowflake/client/core/ResultUtil.java

@@ -83,6 +83,12 @@ public static Object effectiveParamValue(Map<String, Object> parameters, String
   /**
    * Helper function building a formatter for a specialized timestamp type. Note that it will be
    * based on either the 'param' value if set, or the default format provided.
+   *
+   * @param parameters keyed in parameter name and valued in parameter value
+   * @param id id
+   * @param param timestamp output format param
+   * @param defaultFormat default format
+   * @return {@link SnowflakeDateTimeFormat}
    */
   public static SnowflakeDateTimeFormat specializedFormatter(
       Map<String, Object> parameters, String id, String param, String defaultFormat) {

src/main/java/net/snowflake/client/core/SFArrowResultSet.java

@@ -178,7 +178,8 @@ public SFArrowResultSet(
    *
    * @param resultSetSerializable data returned in query response
    * @param telemetryClient telemetryClient
-   * @throws SQLException
+   * @param sortResult set if results should be sorted
+   * @throws SQLException if exception encountered
    */
   public SFArrowResultSet(
       SnowflakeResultSetSerializableV1 resultSetSerializable,