Document null binary operator semantics explicitly

[findepi]

Description

The null-aware binary operators deferred to "Spark rules for null inputs", requiring the reader to already know what those are. Describe the behavior explicitly instead. Spell out the null-propagating behavior of the plain EQUAL, NOT_EQUAL, LOGICAL_AND, and LOGICAL_OR operators. Keep the wording consistent across the codebase (C++ and Java).

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cpp/include/cudf/ast/ast_operator.hpp`:
- Around line 39-40: Update every NOT_EQUAL enum entry to explicitly document
that it returns NULL when either operand is NULL, otherwise returns whether the
operands are unequal: cpp/include/cudf/ast/ast_operator.hpp lines 39-40,
java/src/main/java/ai/rapids/cudf/ast/BinaryOperator.java lines 25-28, and
java/src/main/java/ai/rapids/cudf/BinaryOp.java lines 36-37. Keep the existing
NULL_EQUAL documentation unchanged.

In `@cpp/include/cudf/binaryop.hpp`:
- Around line 73-88: Update the shared output-validity documentation for all
three binary_operation overloads to match the null-aware operator semantics:
NULL_EQUALS and NULL_NOT_EQUALS always produce valid results, while
NULL_LOGICAL_AND and NULL_LOGICAL_OR produce valid results for decisive
false/true cases respectively and null otherwise. Preserve the existing
logical-AND validity rule for other operators and the NULL_MIN/NULL_MAX
exceptions.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: fa155177-3442-4bb5-b326-a327e7f75bd3

📥 Commits

Reviewing files that changed from the base of the PR and between 6a22d1d and 87621eb.

📒 Files selected for processing (4)

• cpp/include/cudf/ast/ast_operator.hpp
• cpp/include/cudf/binaryop.hpp
• java/src/main/java/ai/rapids/cudf/BinaryOp.java
• java/src/main/java/ai/rapids/cudf/ast/BinaryOperator.java

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Clarified equality, logical, and null-safe operator behavior.
  • Added explicit descriptions of null propagation and Kleene three-valued logic.
  • Documented validity behavior for null-safe binary operations.
  • Aligned operator documentation across C++ and Java APIs.
  • Updated the Java copyright year.

Walkthrough

The change updates C++ and Java documentation for binary operator null handling and three-valued logic. Enum values, identifiers, API declarations, and runtime behavior remain unchanged.

Changes

Operator semantics documentation

Layer / File(s)	Summary
Cross-language operator semantics cpp/include/cudf/ast/ast_operator.hpp, cpp/include/cudf/binaryop.hpp, java/src/main/java/ai/rapids/cudf/BinaryOp.java, java/src/main/java/ai/rapids/cudf/ast/BinaryOperator.java	Documentation now specifies null propagation for standard logical and equality operators, null-safe equality results, and Kleene three-valued behavior for null-prefixed logical operators. The Java copyright year is updated to 2026.

Estimated code review effort: 1 (Trivial) | ~4 minutes

Suggested reviewers: mythrocks, davidwendt

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: documenting null binary operator semantics.
Description check	✅ Passed	The description directly explains the documentation changes and their scope across C++ and Java.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[findepi]

As a follow-up I think we could replace ordinary code comments with javadoc / markdown comments.