comphead commented on code in PR #4057: URL: https://github.com/apache/datafusion-comet/pull/4057#discussion_r3138581728
########## docs/source/contributor-guide/adding_a_new_expression.md: ########## @@ -208,6 +210,65 @@ When the query planner encounters an expression: Any notes provided will be logged to help with debugging and understanding why an expression was not used. +#### Documenting Incompatible and Unsupported Reasons + +In addition to `getSupportLevel`, which governs runtime planning decisions, the serde trait exposes two static documentation methods: + +- `getIncompatibleReasons(): Seq[String]` - Reasons the expression may produce different results than Spark. +- `getUnsupportedReasons(): Seq[String]` - Reasons the expression, or certain usages of it, may not be supported by Comet. + +These methods do not affect runtime behavior. They are called by `GenerateDocs` (`spark/src/main/scala/org/apache/comet/GenerateDocs.scala`) when building the user-facing Compatibility Guide pages under `docs/source/user-guide/latest/compatibility/expressions/` (for example, `math.md`, `datetime.md`, `array.md`, `aggregate.md`, `struct.md`). Each reason is rendered as a bullet in the corresponding page. + +Key differences from `getSupportLevel`: + +- **No expression instance.** Both methods take no arguments, so they describe the expression in general rather than a specific call site. Use `getSupportLevel` for checks that depend on data types, argument values, or other per-instance details. +- **Markdown-friendly.** Each returned string is written to a Markdown document, so you can embed backticks, links, and line breaks. Keep each reason self-contained, since they are rendered as separate bullets. +- **Regenerated by CI.** The lists are collected by `GenerateDocs` and published by CI on every merge to `main`. The generated Markdown is not committed to the repo, so you do not need to regenerate or commit it yourself. The reasons do not have to match the `notes` passed to `Compatible`, `Incompatible`, or `Unsupported`, but keeping them consistent avoids confusing users. Review Comment: I dont see `yml` CI changes 🤔 -- 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]
