Add KDoc and tests for ColumnAccessor.nullable()

[zaleslaw]

Add KDoc for ColumnAccessor.nullable()

Closes #1996

ColumnAccessor<T>.nullable() was the only public declaration in ColumnAccessorApi.kt
and had no documentation at all.

The function is easy to misread as a data operation. It is a plain unchecked cast: it
returns the very same accessor object with the value type widened to T?, looks up no
column and reads no value. Two things are worth knowing and were not written down anywhere:

• ColumnAccessor is covariant, so a ColumnAccessor<Double> is already accepted where a
  ColumnAccessor<Double?> is expected. What the call changes is the declared type of the
  accessor itself.
• Without the cast, a null from the column arrives as a null in the non-nullable type
  T and only fails later, at the first use of the value. That is the reason the function
  exists, so the KDoc now says it.

Files

core/.../api/ColumnAccessorApi.kt — the KDoc, following the structure of first.kt.

core/.../test/.../api/ColumnAccessorApi.kt — new ColumnAccessorApiTests, one test per
documented claim.

KDOC_GUIDELINES.md — a note in the "Examples section": keep deprecated API out of KDoc
examples, and where to find the deprecation constants.

Example

The example shows a concat with a frame that has no score column, because that is how
the nulls appear in practice. The same scenario is asserted by the test named
KDoc example nullable, so the example cannot silently rot.

Tests

nullable() had no test of its own before; its only usage was incidental, inside a concat
test.

Nine tests, one per claim: the KDoc example; a null read through a non-nullable accessor
(it returns null and throws NullPointerException only at the first use); the return type
and object identity; the name and the path for a plain, a nested and a column-group
accessor; a missing column and a column without nulls; an already nullable accessor; and the
return type of castToNullable on an accessor, which the "See also" section refers to.

Where the return type is the contract, it is pinned by an explicit type annotation, so the
compiler is the assertion. All expected values are written out literally.

Open questions

Should this function be deprecated instead? Almost everything that reads through an
accessor is already @Deprecated(DEPRECATED_ACCESS_API): df[accessor], row[accessor],
accessor(), df.getColumn(accessor). The only supported reading path left is
accessor.getValue(row), which is why the example uses it. If the Column Accessors API is
going away, nullable() should probably go with it, and this KDoc documents an API on its
way out. Please tell me which way you want it.

inline / reified look unnecessary. cast() here resolves to the non-reified
ColumnAccessor<*>.cast(), and a plain fun <T> ColumnAccessor<T>.nullable() compiles
fine, call sites included. I left the signature untouched, because it is public and out of
scope for a KDoc issue.

@param [T]. The guidelines ask to document type parameters, so I did, but this one is
fully implied by the receiver type. If we do not want such @params, the rule in
KDOC_GUIDELINES.md should be changed as well — today, the rule and the practice disagree
(16 uses across api/).

[Copilot]

🟡 Changes recommended

The central KDoc overstates when null access fails and uses a nonconforming example heading.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Documents and tests the unchecked nullable type cast for ColumnAccessor.

Changes:

• Adds detailed KDoc and usage example.
• Adds focused behavioral tests.
• Clarifies KDoc example guidelines.

File summaries

File	Description
KDOC_GUIDELINES.md	Adds deprecated-API guidance.
core/src/main/.../ColumnAccessorApi.kt	Documents nullable().
core/src/test/.../ColumnAccessorApi.kt	Tests documented behavior.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jetbrains-air]

Thanks for the careful write-up — one blocking point on the new tests to sort out before this goes in.

_{Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=db5ba26f-ebda-4080-aa9b-8d5bf5d64c02}

[jetbrains-air]

Nice, careful work — approving, with one non-blocking note inline.

---

Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=c51059ea-f847-48aa-a1e4-3ace0dbbfef5

[jetbrains-air]

Nice, careful piece of work — approving; one non-blocking note inline.

---

Produced by Air Automations. Name: AI Review / Run: https://air.jetbrains.cloud/org/05cf1a7f-6ab5-713b-abd3-29d0c8a05e2d/automations/8daf2412-0b6c-4433-90c0-b40ab5aebcdb?run=5b630911-72b8-4675-82ec-2f69c4dc5544