Documentation review for WL#15706 and WL#16174.

Change-Id: I1596ef5588a314aea8567a1cbf1737aeeac53d53

src/main/core-api/java/com/mysql/cj/MysqlType.java

@@ -423,15 +423,15 @@ public enum MysqlType implements SQLType {
     GEOMETRY("GEOMETRY", Types.BINARY, null, 0, MysqlType.IS_NOT_DECIMAL, 65535L, ""), // TODO check precision, it isn't well documented, only mentioned that WKB format is represented by BLOB
     /**
      * VECTOR[(M)]
-     * A VECTOR column with a maximum length of 65,532 (16383 x 4) bytes. An optional length M can be given for this type which indicates the maximum number of
-     * entries in the VECTOR, with maximum of 16383. Each entry is a 4 Byte (single-precision) floating-point value.
+     * A VECTOR column with a maximum length of 65,532 (16383 x 4) bytes. An optional length M can be given for this type to indicate the maximum number of
+     * entries in a VECTOR. M cannot exceed 16383. Each entry is a 4 Byte (single-precision) floating-point value.
      *
      * Protocol: FIELD_TYPE_VECTOR = 242
      */
     VECTOR("VECTOR", Types.LONGVARBINARY, null, 0, MysqlType.IS_NOT_DECIMAL, 65532L, "[(M)]"),
 
     /**
-     * Fall-back type for those MySQL data types which c/J can't recognize.
+     * Fall-back type for those MySQL data types which Connector/J cannot recognize.
      * Handled the same as BLOB.
      *
      * Has no protocol ID.

src/main/core-api/java/com/mysql/cj/QueryAttributesBindings.java

@@ -76,7 +76,7 @@ public interface QueryAttributesBindings {
     void runThroughAll(Consumer<BindValue> bindAttribute);
 
     /**
-     * Checks if there's already an attribute with the specified name.
+     * Checks if there is already an attribute with the specified name.
      *
      * @param name
      *            the query attribute name.

src/main/core-api/java/com/mysql/cj/telemetry/TelemetryHandler.java

@@ -30,7 +30,7 @@
 public interface TelemetryHandler {
 
     /**
-     * Start a telemetry span. Additionally, the returned {@link TelemetrySpan} object returned must be made current so that it gets recorded by the telemetry
+     * Start a telemetry span. Additionally, the returned {@link TelemetrySpan} object must be made current so that it gets recorded by the telemetry
      * tracer.
      * A {@link TelemetrySpan} object must be closed in a finally block after being made current, e.g.:
      *
@@ -48,7 +48,7 @@ public interface TelemetryHandler {
      * @param args
      *            arguments used for interpolating the specified span name via {@link String#format(String, Object...)}
      * @return
-     *         the newly created span object
+     *         the newly-created span object
      */
     TelemetrySpan startSpan(TelemetrySpanName spanName, Object... args);
 

src/main/core-api/java/com/mysql/cj/telemetry/TelemetrySpan.java

@@ -23,7 +23,7 @@
 /**
  * A telemetry span wrapper that hides all specific details from the underlying telemetry library.
  *
- * A default no-op implementation is provided so that telemetry may be turned off with minimal impact to the driver code.
+ * A default no-op implementation is provided so that telemetry may be turned off with minimal impact on the driver code.
  */
 public interface TelemetrySpan extends AutoCloseable {
 
@@ -77,7 +77,7 @@ default void end() {
     }
 
     /**
-     * {@link AutoCloseable#close()} that can be used to end this span and, thus, make it possible to create new span within try-with-resources blocks.
+     * {@link AutoCloseable#close()} that can be used to end this span and, making it possible to create new span within the try-with-resources blocks.
      */
     @Override
     default void close() {

src/main/core-api/java/com/mysql/cj/telemetry/TelemetrySpanName.java

@@ -21,7 +21,7 @@
 package com.mysql.cj.telemetry;
 
 /**
- * List of most common telemetry span names.
+ * List of telemetry span names.
  */
 public enum TelemetrySpanName {
 

src/main/core-impl/java/com/mysql/cj/CoreSession.java

@@ -71,7 +71,7 @@ public abstract class CoreSession implements Session {
     /** The event sink to use for profiling */
     private ProfilerEventHandler eventSink;
 
-    /** The Telemetry handler to process telemetry operations */
+    /** The telemetry handler to process telemetry operations */
     private TelemetryHandler telemetryHandler = null;
 
     public CoreSession(HostInfo hostInfo, PropertySet propSet) {

src/main/core-impl/java/com/mysql/cj/NativeQueryAttributesBindings.java

@@ -40,7 +40,7 @@
 
 public class NativeQueryAttributesBindings implements QueryAttributesBindings {
 
-    // Query attributes use a different type mapping than other parameters bindings.
+    // Query attributes use a different type mapping than other parameter bindings.
     private static final Map<Class<?>, MysqlType> DEFAULT_MYSQL_TYPES = new HashMap<>();
     static {
         DEFAULT_MYSQL_TYPES.put(String.class, MysqlType.CHAR);

src/main/core-impl/java/com/mysql/cj/result/DefaultColumnDefinition.java

@@ -213,10 +213,8 @@ public int findColumn(String columnName, boolean useColumnNamesInFindColumn, int
     }
 
     /**
-     * Check if fields with type BLOB, MEDIUMBLOB, LONGBLOB, TEXT, MEDIUMTEXT, LONGTEXT or VECTOR
-     * exist in this ColumnDefinition.
-     * This check is used for making a decision about whether we want to force a
-     * buffer row (better for rows with large fields).
+     * Check if fields with type BLOB, MEDIUMBLOB, LONGBLOB, TEXT, MEDIUMTEXT, LONGTEXT, or VECTOR exist in this ColumnDefinition.
+     * This check is used for making a decision about whether we want to force a buffer row (better for rows with large fields).
      *
      * @return true if this ColumnDefinition has large fields
      */

src/main/protocol-impl/java/com/mysql/cj/protocol/a/NativeProtocol.java

@@ -336,7 +336,7 @@ public Supplier<ValueEncoder> getValueEncoderSupplier(Object obj) {
     }
 
     /**
-     * Negotiates the SSL communications channel used when connecting to a MySQL server that understands SSL.
+     * Negotiates the SSL communication channel used when connecting to a MySQL server that has SSL enabled.
      */
     @Override
     public void negotiateSSLConnection() {

src/main/resources/com/mysql/cj/LocalizedErrorMessages.properties

@@ -902,7 +902,7 @@ ConnectionProperties.noDatetimeStringSync=Don''t ensure that ''ResultSet.getTime
 ConnectionProperties.nullCatalogMeansCurrent=In ''DatabaseMetaData'' methods that take a ''catalog'' or ''schema'' parameter, does the value "null" mean to use the current database? See also the property ''databaseTerm''.
 ConnectionProperties.ociConfigFile=The location of the OCI configuration file as required by the OCI SDK for Java. Default value is "~/.oci/config" for Unix-like systems and "%HOMEDRIVE%%HOMEPATH%.oci\\config" for Windows.
 ConnectionProperties.ociConfigProfile=The profile in the OCI configuration file specified in ''ociConfigFile'', from where the configuration to use in the ''authentication_oci_client'' authentication plugin is to be read.
-ConnectionProperties.openTelemetry=Should the driver generate OpenTelemetry traces and handle context propagation to the MySQL Server? This option accepts the values "REQUIRED", "PREFERRED" and "DISABLED". If set to "REQUIRED", an OpenTelemetry library must be available at run time, or else connections to the MySQL Server will fail. Setting it to "DISABLED", turns off generating OpenTelemetry instrumentation by Connector/J. Setting it to "PREFERRED" enables generating OpenTelemetry instrumentation provided that an OpenTelemetry library is available at run time, and a warning is issued otherwise. Not setting a value for the property is equivalent to setting it as "PREFERRED" but no warning is issued when no OpenTelmetry library is available at run time. Connector/J relies entirely on the OpenTelemetry exporters configured in the calling application and does not provide any means of configuring its own exporters.
+ConnectionProperties.openTelemetry=Should the driver generate OpenTelemetry traces and handle context propagation to the MySQL Server? This option accepts the values "REQUIRED", "PREFERRED", and "DISABLED". If set to "REQUIRED", an OpenTelemetry library must be available at run time, or connections to the MySQL Server will fail. Setting it to "DISABLED" turns off generating OpenTelemetry instrumentation by Connector/J. Setting it to "PREFERRED" enables generating OpenTelemetry instrumentation provided that an OpenTelemetry library is available at run time, and a warning is issued otherwise. Not setting a value for the property is equivalent to setting it as "PREFERRED", but no warning is issued when no OpenTelmetry library is available at run time. Connector/J relies entirely on the OpenTelemetry exporters configured in the calling application and does not provide any means of configuring its own exporters.
 ConnectionProperties.overrideSupportsIEF=Should the driver return "true" for ''DatabaseMetaData.supportsIntegrityEnhancementFacility()'' even if the database doesn''t support it to workaround applications that require this method to return "true" to signal support of foreign keys, even though the SQL specification states that this facility contains much more than just foreign key support (one such application being OpenOffice)?
 ConnectionProperties.packetDebugBufferSize=The maximum number of packets to retain when ''enablePacketDebug'' is "true".
 ConnectionProperties.padCharsWithSpace=If a result set column has the CHAR type and the value does not fill the amount of characters specified in the DDL for the column, should the driver pad the remaining characters with space (for ANSI compliance)?
@@ -922,7 +922,7 @@ ConnectionProperties.processEscapeCodesForPrepStmts=Should the driver process es
 ConnectionProperties.profilerEventHandler=Name of a class that implements the interface ''com.mysql.cj.log.ProfilerEventHandler'' that will be used to handle profiling/tracing events.
 ConnectionProperties.profileSQL=Trace queries and their execution/fetch times to the configured ''profilerEventHandler''.
 ConnectionProperties.queriesBeforeRetrySource=When using multi-host failover, the number of queries to issue before falling back to the primary host when failed over. Whichever condition is met first, ''queriesBeforeRetrySource'' or ''secondsBeforeRetrySource'' will cause an attempt to be made to reconnect to the primary host. Setting both properties to "0" disables the automatic fall back to the primary host at transaction boundaries.
-ConnectionProperties.queryInfoCacheFactory=Name of a class implementing ''com.mysql.cj.CacheAdapterFactory'' which will be used to create caches for the parsed representation of prepared statements. Prior to version 8.0.29, this property was named ''parseInfoCacheFactory'', which remains as an alias.
+ConnectionProperties.queryInfoCacheFactory=Name of a class implementing ''com.mysql.cj.CacheAdapterFactory'', which will be used to create caches for the parsed representation of prepared statements. Prior to version 8.0.29, this property was named ''parseInfoCacheFactory'', which remains as an alias.
 ConnectionProperties.queryInterceptors=A comma-delimited list of classes that implement ''com.mysql.cj.interceptors.QueryInterceptor'' that intercept query executions and are able influence the results. Query iterceptors are chainable: the results returned by the current interceptor will be passed on to the next in the chain, from left-to-right in the order specified in this property.
 ConnectionProperties.queryTimeoutKillsConnection=If the timeout given in ''Statement.setQueryTimeout()'' expires, should the driver forcibly abort the connection instead of attempting to abort the query?
 ConnectionProperties.readFromSourceWhenNoReplicas=Replication-aware connections distribute load by using the source hosts when in read/write state and by using the replica hosts when in read-only state. If, when setting the connection to read-only state, none of the replica hosts are available, an ''SQLException'' is thrown back. Setting this property to "true" allows to fail over to the source hosts, while setting the connection state to read-only, when no replica hosts are available at switch instant.