Kotlin / Kotlin/dataframe

Clarify extension-properties requirements on access/reference documentation pages

Open Beginner friendly
#1,934 0 comments 0 reactions 0 assignees View on GitHub
documentation
Dominant language
Kotlin
Stars
1.1k
Forks
83
Avg merge
4d 12h
Merged PRs (30d)
30

Description

## Problem

The main onboarding pages now explain extension properties much better:

- [Setup Kotlin DataFrame in Gradle](https://kotlin.github.io/dataframe/setupgradle.html) explains that the Kotlin DataFrame Compiler Plugin generates extension properties in Gradle projects.
- [Quickstart Guide](https://kotlin.github.io/dataframe/quickstart.html) shows the schema flow with `generateInterfaces(...)`, `cast()`, and then `dfRepository.full_name`.
- [Extension Properties API](https://kotlin.github.io/dataframe/extensionpropertiesapi.html) explains the difference between Kotlin Notebook and the Compiler Plugin, and notes that DataFrames read from files/URLs need an explicit schema.

However, some access/reference pages still show extension-property examples without local context about when they are available.

For example:

- [Get columns](https://kotlin.github.io/dataframe/getcolumns.html) shows:

```kotlin
df.age
df.name.lastName
```

- [getColumn](https://kotlin.github.io/dataframe/getcolumn.html) shows:

```kotlin
df.getColumn { age }
```

For users landing directly on these pages, especially from search or cross-links, it may still look like `df.age` / `{ age }` work automatically in any Gradle project. In reality, extension properties require generated schemas:

- in Kotlin Notebook, after executing a cell with a `DataFrame` variable;
- in Gradle/Maven projects, via the Kotlin DataFrame Compiler Plugin and an available schema;
- otherwise users should use string access, column accessors, or other non-generated access APIs.

This gap was originally reported in #703.

## Expected

Access/reference documentation pages that show extension-property examples should include a short note or link explaining the requirement for generated extension properties.

## Suggested wording

A short reusable note could be added near extension-property examples:

> Extension-property examples require generated DataFrame schemas. In Kotlin Notebook, they are generated after cell execution. In Gradle/Maven projects, enable the Kotlin DataFrame Compiler Plugin and provide or cast to a schema. Without generated schemas, use string access or column-accessor APIs.

Relevant links:

- [Extension Properties API](https://kotlin.github.io/dataframe/extensionpropertiesapi.html)
- [Setup Kotlin DataFrame in Gradle](https://kotlin.github.io/dataframe/setupgradle.html)
- [Quickstart Guide](https://kotlin.github.io/dataframe/quickstart.html)
- [Data Schemas in Gradle projects](https://kotlin.github.io/dataframe/schemasgradle.html)

## Definition of Done

- Add a note or link to access/reference pages that prominently show extension-property examples.
- At minimum, check/update:
- [Get columns](https://kotlin.github.io/dataframe/getcolumns.html)
- [getColumn](https://kotlin.github.io/dataframe/getcolumn.html)
- Make it clear that `df.age`, `df.name.lastName`, and `{ age }` require generated extension properties.
- Point Gradle/Maven users to compiler plugin and schema setup docs.
- Mention string access / column accessors as alternatives when no generated schema is available.
- Link this issue from #703 before closing it as answered/support thread.

Contributor guide

Open the contributing guide

Research direction

Start with the Get columns and getColumn documentation pages, then review Extension Properties API, Setup Kotlin DataFrame in Gradle, Quickstart Guide, and Data Schemas in Gradle projects for consistent wording and links. Add a note near the extension-property examples explaining generated schemas, compiler-plugin setup, and alternatives without a schema; update any other prominent examples and link this issue from #703.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
Half a day
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
85/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.