Clarify extension-properties requirements on access/reference documentation pages
- 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
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