LuciferYang opened a new pull request, #57377:
URL: https://github.com/apache/spark/pull/57377
### What changes were proposed in this pull request?
This PR corrects scaladoc/comments across the `sql/api` module that
contradict the code -- copy-paste artifacts, wrong parameter names, examples
calling the wrong symbol, and stale or incorrect statements. It is
documentation-only; no behavior changes. 19 files are touched. Highlights:
- `SQLContext.tables()` / `tables(databaseName)` documented a `database`
column, but the output schema (via `mapTableDatasetOutput`) emits `namespace`.
- `DataFrameStatFunctions.corr`: the examples on the 2-arg and 3-arg
overloads were swapped (each demonstrated the other overload).
- `Dataset.groupingSets`: the second example was missing the outer
`Seq(...)` wrapper, so it had the wrong argument type and unbalanced
parentheses -- it would not compile.
- `SparkSession.config(String, String)`: removed the incorrect `@note` "this
is only supported in Connect mode" -- it works in Classic too (the
`@ClassicOnly` `appName`/`master`/`enableHiveSupport` all delegate to it).
- `SparkDateTimeUtils.truncateTimeToPrecision`: the example used
microseconds for a method that operates on nanoseconds.
- `catalog.interface`: `Database.catalog`, `Function.catalog`, and
`Function.namespace` `@param` docs said "table" (pasted from `Table`).
`Catalog.createExternalTable` and `SQLContext.createExternalTable`
options-based overloads said "from the given path" although they take no path
argument.
- `DataTypes.createMapType` (values documented as `keyType`),
`TimestampNTZType` (byte-code type name missing `$`),
`NonEmptyNamespaceException` ("already exists" vs not-empty namespace),
`QueryParsingErrors.cursorInvalidQualifierError` (`@throws`/"Always throws" but
it returns the exception), `StructType` (class doc claimed missing names are
ignored / `null` returned, but `apply` throws), `PositionMapper` ("binary
search / O(log k)" over a linear `.find`; one wrong example offset),
`DateTimeFormatterHelper` (stale "synchronised omitted" comment vs
`synchronizedMap.computeIfAbsent`), `StringConcat.append` ("Returns true" on a
`Unit` method), `SinkProgress.description` ("source" vs sink),
`UserDefinedAggregateFunction.bufferSchema` ("input arguments" vs buffer
values), and `DataTypeAstBuilder` (a `GEOGRAPHY` branch comment saying
"geometry"; `visitIdentityColumn` `@return` "Tuple" vs `IdentityColumnSpec`).
### Why are the changes needed?
The documentation misdescribes these APIs and internals. Some are
user-facing (e.g. `SQLContext.tables` names a column that does not exist, so
`.select("database")` would fail; `config`'s note wrongly restricts it to
Connect), and the rest are misleading comments that can send readers to the
wrong behavior.
### Does this PR introduce _any_ user-facing change?
No. Documentation/comment-only changes.
### How was this patch tested?
No tests; documentation-only. `sql-api` compiles, and `scalafmt` validation
passes on the module. Each correction was verified against the corresponding
signature/body (and, where semantics were involved, against the catalyst
expression or builder it maps to). Changed lines stay within 100 chars and
introduce no non-ASCII characters.
### Was this patch authored or co-authored using generative AI tooling?
Generated-by: Claude Code (Opus 4.8)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
