Kotlin / Kotlin/dataframe

Update access API documentation and KDocs before release

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

Description

We now have a bit strange duplication:
https://kotlin.github.io/dataframe/apilevels.html - no mention of compiler plugin, page looks strange because it used to show 4 APIs and now it's 2 + example is not compatible with compiler plugin, only works in notebooks

Top level page with big banner on the top:
https://kotlin.github.io/dataframe/extensionpropertiesapi.html

I think these two should be somehow merged

In kdocs also no mention of compiler plugin here:
org.jetbrains.kotlinx.dataframe.documentation.AccessApi.ExtensionPropertiesApi

ApiLevels needs to be moved to samples module.

========================================================================================

# Update access API documentation and KDocs before release

## Motivation

Access API docs are currently inconsistent and partially outdated:

- `apilevels.html` still looks like an old overview page and does not mention the compiler plugin.
- Its example is not compatible with compiler-plugin usage and only works in notebook-style scenarios.
- `extensionpropertiesapi.html` is a separate top-level page with overlapping content.
- KDocs for `AccessApi.ExtensionPropertiesApi` also do not mention the compiler plugin.
- `ApiLevels` samples should be moved to the samples module.

Before release, users should see one clear story for typed column access: how extension properties work, when the compiler plugin is needed, and how this relates to the remaining access APIs.

## Scope

- Merge or reorganize `apilevels.html` and `extensionpropertiesapi.html` to remove duplication.
- Update examples so they work for regular compiler-plugin usage, not only notebook scenarios.
- Mention the compiler plugin in relevant docs and KDocs.
- Move `ApiLevels` examples to the samples module.

## Definition of Done

- Access API docs have no duplicated or contradictory top-level pages.
- Compiler plugin is clearly documented as the main way to use generated extension properties.
- Examples compile in the intended non-notebook setup.
- `AccessApi.ExtensionPropertiesApi` KDocs are updated.
- `ApiLevels` samples are moved and validated through the docs/sample pipeline.

Contributor guide

Open the contributing guide

Research direction

Start by comparing apilevels.html and extensionpropertiesapi.html, then read the AccessApi.ExtensionPropertiesApi KDocs and locate the ApiLevels samples. Reorganize the overlapping documentation, document compiler-plugin usage, update the examples for non-notebook use, and move ApiLevels to the samples module. Validate the examples and documentation through the docs/sample pipeline.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.