andygrove opened a new pull request, #106:
URL: https://github.com/apache/datafusion-spark/pull/106
Part of #55
## Rationale
#58 set out how to document functions with `#[user_doc]`, using `sha2` and
`substring` as examples. This PR applies it to the date arithmetic and
field-extraction functions, so they show up in generated function references.
## Changes
- Document these functions with `#[user_doc]` and implement
`documentation()`: `date_add` (alias `dateadd`), `date_sub`, `date_diff` (alias
`datediff`), `add_months`, `next_day`, `last_day`, `weekday`, `date_part`
(alias `datepart`), `hour`, `minute`, `second` and `unix_date`.
- `unix_micros`, `unix_millis` and `unix_seconds` share one struct
(`SparkUnixTimestamp`), and `#[user_doc]` only gives one doc per struct. Their
docs are built per time unit with `Documentation::builder`, so each has its own
syntax and examples.
- Cut each struct's rustdoc down to a one-line summary and the Spark docs
link. Rustdoc on public constructors is unchanged.
- Points the docs call out:
- `date_add`, `date_sub` and `add_months` take INT, SMALLINT or TINYINT
(INT only for `add_months`). Integer literals are BIGINT in DataFusion, so they
need a cast such as `1::INT`.
- Several functions don't implicitly cast strings to DATE or TIMESTAMP the
way Spark does.
- `next_day` returns NULL for an unrecognized day name even when ANSI mode
is on, where Spark raises an error.
- `date_part('SECOND', ...)` returns whole seconds, where Spark returns
DECIMAL(8, 6).
- Add SLT cases to `second.slt` and `date_part.slt` showing that fractions
of a second are dropped, since the docs state it.
The truncation, time zone and interval functions in `datetime` are left for
a separate PR. `monthname` is left out because #75 changes it.
## Testing
- `cargo fmt`, `cargo clippy --all-targets --all-features -- -D warnings`,
`cargo test -p datafusion-spark` and `cargo test -p
datafusion-spark-sqllogictest` pass.
- I ran every SQL example in the docs through the sqllogictest runner, and
they all match.
- Everything else the docs describe is covered by the existing SLT tests or
visible in the function signatures. That covers the overflow, NULL and
floor-rounding behavior and the rejected string inputs.
## User-facing changes
`documentation()` now returns docs for these functions. Behavior does not
change.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
--
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]
