[SPARK-58220][SQL] Fix scaladoc and comment errors across sql/api

sql/api/src/main/java/org/apache/spark/sql/types/DataTypes.java

@@ -206,7 +206,7 @@ public static YearMonthIntervalType createYearMonthIntervalType() {
 
   /**
    * Creates a MapType by specifying the data type of keys ({@code keyType}) and values
-   * ({@code keyType}). The field of {@code valueContainsNull} is set to {@code true}.
+   * ({@code valueType}). The field of {@code valueContainsNull} is set to {@code true}.
    */
   public static MapType createMapType(DataType keyType, DataType valueType) {
     if (keyType == null) {
@@ -220,7 +220,7 @@ public static MapType createMapType(DataType keyType, DataType valueType) {
 
   /**
    * Creates a MapType by specifying the data type of keys ({@code keyType}), the data type of
-   * values ({@code keyType}), and whether values contain any null value
+   * values ({@code valueType}), and whether values contain any null value
    * ({@code valueContainsNull}).
    */
   public static MapType createMapType(

sql/api/src/main/scala/org/apache/spark/sql/DataFrameStatFunctions.scala

@@ -141,7 +141,7 @@ abstract class DataFrameStatFunctions {
    * {{{
    *    val df = sc.parallelize(0 until 10).toDF("id").withColumn("rand1", rand(seed=10))
    *      .withColumn("rand2", rand(seed=27))
-   *    df.stat.corr("rand1", "rand2")
+   *    df.stat.corr("rand1", "rand2", "pearson")
    *    res1: Double = 0.613...
    * }}}
    * @since 1.4.0
@@ -161,7 +161,7 @@ abstract class DataFrameStatFunctions {
    * {{{
    *    val df = sc.parallelize(0 until 10).toDF("id").withColumn("rand1", rand(seed=10))
    *      .withColumn("rand2", rand(seed=27))
-   *    df.stat.corr("rand1", "rand2", "pearson")
+   *    df.stat.corr("rand1", "rand2")
    *    res1: Double = 0.613...
    * }}}
    * @since 1.4.0

sql/api/src/main/scala/org/apache/spark/sql/DataFrameWriter.scala

@@ -236,7 +236,7 @@ abstract class DataFrameWriter[T] {
   def save(path: String): Unit
 
   /**
-   * Saves the content of the `DataFrame` as the specified table.
+   * Saves the content of the `DataFrame`.
    *
    * @since 1.4.0
    */

sql/api/src/main/scala/org/apache/spark/sql/Dataset.scala

@@ -1517,7 +1517,7 @@ abstract class Dataset[T] extends Serializable {
    *   ds.groupingSets(Seq(Seq($"department", $"group"), Seq()), $"department", $"group").avg()
    *
    *   // Compute the max age and average salary, group by specific grouping sets.
-   *   ds.groupingSets(Seq($"department", $"gender"), Seq()), $"department", $"group").agg(Map(
+   *   ds.groupingSets(Seq(Seq($"department", $"gender"), Seq()), $"department", $"group").agg(Map(
    *     "salary" -> "avg",
    *     "age" -> "max"
    *   ))

sql/api/src/main/scala/org/apache/spark/sql/SQLContext.scala

@@ -430,8 +430,8 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
   /**
    * Returns a `DataStreamReader` that can be used to read streaming data in as a `DataFrame`.
    * {{{
-   *   sparkSession.readStream.parquet("/path/to/directory/of/parquet/files")
-   *   sparkSession.readStream.schema(schema).json("/path/to/directory/of/json/files")
+   *   sqlContext.readStream.parquet("/path/to/directory/of/parquet/files")
+   *   sqlContext.readStream.schema(schema).json("/path/to/directory/of/json/files")
    * }}}
    *
    * @since 2.0.0
@@ -463,8 +463,8 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
   }
 
   /**
-   * Creates an external table from the given path based on a data source and a set of options.
-   * Then, returns the corresponding DataFrame.
+   * Creates an external table based on the dataset in a data source and a set of options. Then,
+   * returns the corresponding DataFrame.
    *
    * @group ddl_ops
    * @since 1.3.0
@@ -478,8 +478,8 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
   }
 
   /**
-   * (Scala-specific) Creates an external table from the given path based on a data source and a
-   * set of options. Then, returns the corresponding DataFrame.
+   * (Scala-specific) Creates an external table based on the dataset in a data source and a set of
+   * options. Then, returns the corresponding DataFrame.
    *
    * @group ddl_ops
    * @since 1.3.0
@@ -493,7 +493,7 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
   }
 
   /**
-   * Create an external table from the given path based on a data source, a schema and a set of
+   * Create an external table based on the dataset in a data source, a schema and a set of
    * options. Then, returns the corresponding DataFrame.
    *
    * @group ddl_ops
@@ -509,8 +509,8 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
   }
 
   /**
-   * (Scala-specific) Create an external table from the given path based on a data source, a
-   * schema and a set of options. Then, returns the corresponding DataFrame.
+   * (Scala-specific) Create an external table based on the dataset in a data source, a schema and
+   * a set of options. Then, returns the corresponding DataFrame.
    *
    * @group ddl_ops
    * @since 1.3.0
@@ -598,7 +598,7 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
 
   /**
    * Returns a `DataFrame` containing names of existing tables in the current database. The
-   * returned DataFrame has three columns, database, tableName and isTemporary (a Boolean
+   * returned DataFrame has three columns, namespace, tableName and isTemporary (a Boolean
    * indicating if a table is a temporary one or not).
    *
    * @group ddl_ops
@@ -610,7 +610,7 @@ abstract class SQLContext private[sql] (val sparkSession: SparkSession)
 
   /**
    * Returns a `DataFrame` containing names of existing tables in the given database. The returned
-   * DataFrame has three columns, database, tableName and isTemporary (a Boolean indicating if a
+   * DataFrame has three columns, namespace, tableName and isTemporary (a Boolean indicating if a
    * table is a temporary one or not).
    *
    * @group ddl_ops

sql/api/src/main/scala/org/apache/spark/sql/SparkSession.scala

@@ -1167,8 +1167,6 @@ private[sql] abstract class SparkSessionBuilder {
    * Sets a config option. Options set using this method are automatically propagated to both
    * `SparkConf` and SparkSession's own configuration.
    *
-   * @note
-   *   this is only supported in Connect mode.
    * @since 2.0.0
    */
   def config(key: String, value: String): this.type = safePutConfig(key, value)

sql/api/src/main/scala/org/apache/spark/sql/catalog/Catalog.scala

@@ -332,8 +332,8 @@ abstract class Catalog {
   def createTable(tableName: String, path: String, source: String): DataFrame
 
   /**
-   * Creates a table from the given path based on a data source and a set of options. Then,
-   * returns the corresponding DataFrame.
+   * Creates a table based on the dataset in a data source and a set of options. Then, returns the
+   * corresponding DataFrame.
    *
    * @param tableName
    *   is either a qualified or unqualified name that designates a table. If no database
@@ -365,8 +365,8 @@ abstract class Catalog {
   }
 
   /**
-   * (Scala-specific) Creates a table from the given path based on a data source and a set of
-   * options. Then, returns the corresponding DataFrame.
+   * (Scala-specific) Creates a table based on the dataset in a data source and a set of options.
+   * Then, returns the corresponding DataFrame.
    *
    * @param tableName
    *   is either a qualified or unqualified name that designates a table. If no database
@@ -393,8 +393,8 @@ abstract class Catalog {
   def createTable(tableName: String, source: String, options: Map[String, String]): DataFrame
 
   /**
-   * Create a table from the given path based on a data source, a schema and a set of options.
-   * Then, returns the corresponding DataFrame.
+   * Create a table based on the dataset in a data source, a schema and a set of options. Then,
+   * returns the corresponding DataFrame.
    *
    * @param tableName
    *   is either a qualified or unqualified name that designates a table. If no database
@@ -464,8 +464,8 @@ abstract class Catalog {
   }
 
   /**
-   * (Scala-specific) Create a table from the given path based on a data source, a schema and a
-   * set of options. Then, returns the corresponding DataFrame.
+   * (Scala-specific) Create a table based on the dataset in a data source, a schema and a set of
+   * options. Then, returns the corresponding DataFrame.
    *
    * @param tableName
    *   is either a qualified or unqualified name that designates a table. If no database

sql/api/src/main/scala/org/apache/spark/sql/catalog/interface.scala

@@ -72,7 +72,7 @@ class CatalogTableProperty(val key: String, val value: String)
  * @param name
  *   name of the database.
  * @param catalog
- *   name of the catalog that the table belongs to.
+ *   name of the catalog that the database belongs to.
  * @param description
  *   description of the database.
  * @param locationUri
@@ -222,9 +222,9 @@ class Column(
  * @param name
  *   name of the function.
  * @param catalog
- *   name of the catalog that the table belongs to.
+ *   name of the catalog that the function belongs to.
  * @param namespace
- *   the namespace that the table belongs to.
+ *   the namespace that the function belongs to.
  * @param description
  *   description of the function; description can be null.
  * @param className

sql/api/src/main/scala/org/apache/spark/sql/catalyst/analysis/NonEmptyException.scala

@@ -21,8 +21,8 @@ import org.apache.spark.sql.AnalysisException
 import org.apache.spark.sql.catalyst.util.QuotingUtils.quoted
 
 /**
- * Thrown by a catalog when an item already exists. The analyzer will rethrow the exception as an
- * [[org.apache.spark.sql.AnalysisException]] with the correct position information.
+ * Thrown by a catalog when a namespace is not empty. The analyzer will rethrow the exception as
+ * an [[org.apache.spark.sql.AnalysisException]] with the correct position information.
  */
 case class NonEmptyNamespaceException(
     namespace: Array[String],

sql/api/src/main/scala/org/apache/spark/sql/catalyst/parser/DataTypeAstBuilder.scala

@@ -394,8 +394,9 @@ class DataTypeAstBuilder extends SqlBaseParserBaseVisitor[AnyRef] with DataTypeE
           }
           TimeType(precision)
         case GEOGRAPHY =>
-          // Unparameterized geometry type isn't supported and will be caught by the default branch.
-          // Here, we only handle the parameterized GEOGRAPHY type syntax, which comes in two forms:
+          // Unparameterized geography type isn't supported and will be caught by the default
+          // branch. Here, we only handle the parameterized GEOGRAPHY type syntax, which comes in
+          // two forms:
           if (currentCtx.any != null) {
             // The special parameterized GEOGRAPHY type syntax uses a single "ANY" string value.
             // This implies a mixed GEOGRAPHY type, with potentially different SRIDs across rows.
@@ -615,7 +616,7 @@ class DataTypeAstBuilder extends SqlBaseParserBaseVisitor[AnyRef] with DataTypeE
    * @param dataType
    *   The data type of column defined as IDENTITY column. Used for verification.
    * @return
-   *   Tuple containing start, step and allowExplicitInsert.
+   *   IdentityColumnSpec containing start, step and allowExplicitInsert.
    */
   protected def visitIdentityColumn(
       ctx: IdentityColumnContext,

sql/api/src/main/scala/org/apache/spark/sql/catalyst/parser/PositionMapper.scala

@@ -47,7 +47,7 @@ case class PositionRange(
 /**
  * Maps positions between original SQL text and substituted SQL text using sparse ranges.
  *
- * This implementation uses O(k) space and O(log k) lookup time where k = number of substitutions.
+ * This implementation uses O(k) space and O(k) lookup time where k = number of substitutions.
  *
  * @param originalText
  *   The original SQL text with parameter markers
@@ -65,16 +65,16 @@ case class PositionMapper(
   private val positionRanges = buildPositionRanges()
 
   /**
-   * Map a position in the substituted text back to the original text. Uses binary search for
-   * O(log k) lookup time.
+   * Map a position in the substituted text back to the original text. Uses a linear scan over the
+   * substitution ranges.
    *
    * @param substitutedPos
    *   Position in the substituted text
    * @return
    *   Position in the original text, or the same position if no mapping exists
    */
   def mapToOriginal(substitutedPos: Int): Int = {
-    // Binary search for the range containing this position
+    // Linear scan for the range containing this position
     positionRanges.find(range =>
       substitutedPos >= range.substitutedStart && substitutedPos < range.substitutedEnd) match {
       case Some(range) =>
@@ -101,7 +101,7 @@ case class PositionMapper(
    *
    * Creates PositionRanges:
    *   - Range for "'John'": substituted[7,13) -> original[7,12), offset=-1
-   *   - Range for "25": substituted[15,17) -> original[14,18), offset=-3
+   *   - Range for "25": substituted[15,17) -> original[14,18), offset=2
    *
    * This allows mapping any position in "SELECT 'John', 25" back to "SELECT :name, :age".
    */

sql/api/src/main/scala/org/apache/spark/sql/catalyst/util/DateTimeFormatterHelper.scala

@@ -113,12 +113,10 @@ trait DateTimeFormatterHelper {
     ZonedDateTime.of(localDate, localTime, zoneId)
   }
 
-  // Gets a formatter from the cache or creates new one. The buildFormatter method can be called
-  // a few times with the same parameters in parallel if the cache does not contain values
-  // associated to those parameters. Since the formatter is immutable, it does not matter.
-  // In this way, synchronised is intentionally omitted in this method to make parallel calls
-  // less synchronised.
-  // The Cache.get method is not used here to avoid creation of additional instances of Callable.
+  // Gets a formatter from the cache or creates a new one. The cache is a synchronized map, so
+  // computeIfAbsent holds the map's monitor for the whole call and buildFormatter runs at most
+  // once per key. The Cache.get method is not used here to avoid creation of additional instances
+  // of Callable.
   protected def getOrCreateFormatter(
       pattern: String,
       locale: Locale,

sql/api/src/main/scala/org/apache/spark/sql/catalyst/util/SparkDateTimeUtils.scala

@@ -163,8 +163,8 @@ trait SparkDateTimeUtils {
    * Truncates a time value (in nanoseconds) to the specified fractional precision `p`.
    *
    * For example, if `p = 3`, we keep millisecond resolution and discard any digits beyond the
-   * thousand-nanosecond place. So a value like `123456` microseconds (12:34:56.123456) becomes
-   * `123000` microseconds (12:34:56.123).
+   * millisecond place. So a value like `123456789` nanoseconds (12:34:56.123456789) becomes
+   * `123000000` nanoseconds (12:34:56.123).
    *
    * @param nanos
    *   The original time in nanoseconds.

sql/api/src/main/scala/org/apache/spark/sql/catalyst/util/StringConcat.scala

@@ -30,8 +30,7 @@ class StringConcat(val maxLength: Int = ByteArrayUtils.MAX_ROUNDED_ARRAY_LENGTH)
 
   /**
    * Appends a string and accumulates its length to allocate a string buffer for all appended
-   * strings once in the toString method. Returns true if the string still has room for further
-   * appends before it hits its max limit.
+   * strings once in the toString method.
    */
   def append(s: String): Unit = {
     if (s != null) {

sql/api/src/main/scala/org/apache/spark/sql/errors/QueryParsingErrors.scala

@@ -1050,13 +1050,13 @@ private[sql] object QueryParsingErrors extends DataTypeErrorsBase {
   }
 
   /**
-   * Throws an exception when a cursor reference has more than one qualifier. Valid: cursor or
-   * label.cursor Invalid: a.b.cursor
+   * Returns an exception for a cursor reference that has more than one qualifier. Valid: cursor
+   * or label.cursor Invalid: a.b.cursor
    *
    * @param cursorName
    *   The fully qualified cursor name with multiple qualifiers
-   * @throws ParseException
-   *   Always throws this exception
+   * @return
+   *   A ParseException to be thrown by the caller
    */
   def cursorInvalidQualifierError(cursorName: String): Throwable = {
     new ParseException(

sql/api/src/main/scala/org/apache/spark/sql/expressions/udaf.scala

@@ -67,7 +67,7 @@ abstract class UserDefinedAggregateFunction extends Serializable with UserDefine
    * ```
    *
    * The name of a field of this `StructType` is only used to identify the corresponding buffer
-   * value. Users can choose names to identify the input arguments.
+   * value. Users can choose names to identify the buffer values.
    *
    * @since 1.5.0
    */

sql/api/src/main/scala/org/apache/spark/sql/streaming/progress.scala

@@ -350,7 +350,7 @@ class SourceProgress protected[spark] (
  * trigger. See [[StreamingQueryProgress]] for more information.
  *
  * @param description
- *   Description of the source corresponding to this status.
+ *   Description of the sink corresponding to this status.
  * @param numOutputRows
  *   Number of rows written to the sink or -1 for Continuous Mode (temporarily) or Sink V1 (until
  *   decommissioned).

sql/api/src/main/scala/org/apache/spark/sql/types/StructType.scala

@@ -43,8 +43,8 @@ import org.apache.spark.util.{SparkCollectionUtils, SparkStringUtils}
  * }}}
  * For a [[StructType]] object, one or multiple [[StructField]]s can be extracted by names. If
  * multiple [[StructField]]s are extracted, a [[StructType]] object will be returned. If a
- * provided name does not have a matching field, it will be ignored. For the case of extracting a
- * single [[StructField]], a `null` will be returned.
+ * provided name does not have a matching field, an `IllegalArgumentException` is thrown, whether
+ * extracting a single [[StructField]] or multiple.
  *
  * Scala Example:
  * {{{

sql/api/src/main/scala/org/apache/spark/sql/types/TimestampNTZType.scala

@@ -47,9 +47,9 @@ class TimestampNTZType private () extends DatetimeType {
 
 /**
  * The companion case object and its class is separated so the companion object also subclasses
- * the TimestampNTZType class. Otherwise, the companion object would be of type "TimestampNTZType"
- * in byte code. Defined with a private constructor so the companion object is the only possible
- * instantiation.
+ * the TimestampNTZType class. Otherwise, the companion object would be of type
+ * "TimestampNTZType$" in byte code. Defined with a private constructor so the companion object is
+ * the only possible instantiation.
  *
  * @since 3.4.0
  */