feat: add KDoc generation for properties, enum constants, and endpoints by halotukozak · Pull Request #32 · AVSystem/justworks

halotukozak · 2026-03-25T12:55:46Z

Summary

Add description field to Endpoint, valueDescriptions to EnumModel
Parser extracts operation.description and x-enum-descriptions
ModelGenerator adds KDoc to properties with descriptions and per-constant KDoc from valueDescriptions
ClientGenerator generates KDoc with summary/description/@param/@return for endpoints
Tests verify all KDoc generation scenarios

Test plan

Unit tests for property KDoc presence/absence
Unit tests for enum constant KDoc from valueDescriptions
Unit tests for endpoint KDoc with summary, description, params, return

🤖 Generated with Claude Code

@return

- Add description field to Endpoint, valueDescriptions to EnumModel - Parser extracts operation.description and x-enum-descriptions - ModelGenerator adds KDoc to properties and enum constants - ClientGenerator adds KDoc with summary/description/@param/@return - Tests verify all KDoc generation scenarios Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

github-actions · 2026-03-25T12:58:07Z

Coverage Report

Overall Project	96.03% `-0.34%`	🍏
Files changed	92.38%	🍏

File	Coverage
ClientGenerator.kt	99.63% `-0.37%`	🍏
NameUtils.kt	97.92%	🍏
ApiSpec.kt	97.68%	🍏
ModelGenerator.kt	96.72% `-1.35%`	❌
SpecParser.kt	94.03% `-0.13%`	🍏

Copilot

Pull request overview

Adds richer documentation support to the OpenAPI-to-Kotlin codegen pipeline by carrying more descriptive metadata through the parsed model and emitting it as KDoc in generated model/client code.

Changes:

Extend intermediate model: Endpoint.description and EnumModel.valueDescriptions.
Parse operation.description and x-enum-descriptions into the intermediate model.
Generate KDoc for schema properties, enum constants, and client endpoint functions; add unit tests for the new KDoc behaviors.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt	Adds fields to intermediate model to carry endpoint/enum documentation.
core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt	Extracts endpoint descriptions and enum value descriptions from OpenAPI/extensions.
core/src/main/kotlin/com/avsystem/justworks/core/gen/ModelGenerator.kt	Emits property and enum-constant KDoc based on descriptions/valueDescriptions.
core/src/main/kotlin/com/avsystem/justworks/core/gen/ClientGenerator.kt	Emits endpoint KDoc including summary/description/params/return.
core/src/test/kotlin/com/avsystem/justworks/core/gen/ModelGeneratorTest.kt	Adds tests for property and enum-constant KDoc generation.
core/src/test/kotlin/com/avsystem/justworks/core/gen/ClientGeneratorTest.kt	Adds tests for endpoint KDoc generation scenarios.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/main/kotlin/com/avsystem/justworks/core/gen/ClientGenerator.kt

core/src/main/kotlin/com/avsystem/justworks/core/gen/ModelGenerator.kt

- Update EnumModel to use structured `Value` objects instead of raw strings. - Adjust ModelGenerator and SpecParser for new `Value` format. - Refactor related tests to validate `Value` usage and associated descriptions.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt

…nerator

…ndpoints - Introduced `sanitizeKdoc()` to clean input before adding to KDoc. - Updated ModelGenerator and ClientGenerator to apply sanitization. - Removed unused `simpleTypeName()` helper from Client

- Escapes comment terminators (`*/`, `/*`) to prevent broken Kotlin source generation.

- Ensure key-value consistency when mapping `x-enum-descriptions` extensions. - Replace invalid map entries with `emptyMap` for

Port KDoc generation to refactored client/ClientGenerator.kt, preserve x-enum-descriptions support and EnumModel.Value in SpecParser, fix test compilation after merge. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

# Conflicts: # core/src/main/kotlin/com/avsystem/justworks/core/gen/client/ClientGenerator.kt # core/src/main/kotlin/com/avsystem/justworks/core/gen/model/ModelGenerator.kt # core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

# Conflicts: # core/src/main/kotlin/com/avsystem/justworks/core/gen/model/ModelGenerator.kt

janwawszczak

The new code correctly uses sanitizeKdoc() everywhere, but there are 3 pre-existing places in ModelGenerator that also emit descriptions into KDoc without sanitization (generateSealedInterface:248, generateDataClass:428, generateTypeAlias:647). Since this PR is already adding sanitization across the board, could you include these 3 lines as well for consistency?

Without this, if an OpenAPI schema description contains */, the generated Kotlin file will have a broken KDoc comment — the / will prematurely close the comment block, causing everything after it to be treated as code, resulting in a compilation error in the generated sources. Similarly, a stray / in a description could open an unexpected comment block that swallows the following generated code.

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt

core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt

…r tests - Add `sanitizeKdoc` to handle special characters in schema descriptions. - Replace `${'$'}ref` with `$ref` in test specifications for better consistency.

…dability - Add `description = null` field in multiple test cases for improved APISpec coverage. - Refactor tests to use `assert` for clearer error messaging. - Fix minor formatting issues in `PropertyModel` and test comments. - Replace `filterIsInstance<com.squareup.kotlinpoet.TypeSpec>` with `filterIsInstance<TypeSpec>` for consistency.

janwawszczak

Good job! Thx for changes :)

Copilot AI review requested due to automatic review settings March 25, 2026 12:55

Copilot started reviewing on behalf of halotukozak March 25, 2026 12:56 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

refactor: replace string-based enums with EnumModel.Value objects

1e595bb

- Update EnumModel to use structured `Value` objects instead of raw strings. - Adjust ModelGenerator and SpecParser for new `Value` format. - Refactor related tests to validate `Value` usage and associated descriptions.

halotukozak requested a review from Copilot March 25, 2026 13:49

Copilot started reviewing on behalf of halotukozak March 25, 2026 13:50 View session

Copilot AI reviewed Mar 25, 2026

View reviewed changes

core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt Show resolved Hide resolved

core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt Show resolved Hide resolved

halotukozak added 4 commits March 25, 2026 15:08

refactor: remove unused import of ParameterizedTypeName from ClientGe…

2a5b3bc

…nerator

refactor: sanitize KDoc content for properties, enum constants, and e…

6f0ef4f

…ndpoints - Introduced `sanitizeKdoc()` to clean input before adding to KDoc. - Updated ModelGenerator and ClientGenerator to apply sanitization. - Removed unused `simpleTypeName()` helper from Client

feat: add sanitizeKdoc() to clean strings for safe inclusion in KDoc

11a4a32

- Escapes comment terminators (`*/`, `/*`) to prevent broken Kotlin source generation.

refactor: improve handling of schema extension mappings in SpecParser

cb358d0

- Ensure key-value consistency when mapping `x-enum-descriptions` extensions. - Replace invalid map entries with `emptyMap` for

halotukozak self-assigned this Mar 25, 2026

halotukozak and others added 2 commits March 26, 2026 14:04

Merge branch 'master' into docs/kdoc

3f0cbac

ktlint

e017a3c

halotukozak changed the base branch from master to feat/content-types March 30, 2026 15:19

halotukozak and others added 2 commits March 30, 2026 17:32

halotukozak requested a review from janwawszczak March 30, 2026 16:59

Base automatically changed from feat/content-types to master March 31, 2026 10:31

Merge branch 'master' into docs/kdoc

16605ff

# Conflicts: # core/src/main/kotlin/com/avsystem/justworks/core/gen/model/ModelGenerator.kt

janwawszczak requested changes Apr 2, 2026

View reviewed changes

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt Show resolved Hide resolved

core/src/main/kotlin/com/avsystem/justworks/core/parser/SpecParser.kt Show resolved Hide resolved

core/src/main/kotlin/com/avsystem/justworks/core/model/ApiSpec.kt Outdated Show resolved Hide resolved

halotukozak added 3 commits April 2, 2026 15:23

test: add SpecParser tests for x-enum-descriptions handling in enums

760a8e6

fix: sanitize KDoc descriptions and correct $ref usage in SpecParse…

aedf458

…r tests - Add `sanitizeKdoc` to handle special characters in schema descriptions. - Replace `${'$'}ref` with `$ref` in test specifications for better consistency.

janwawszczak approved these changes Apr 2, 2026

View reviewed changes

halotukozak merged commit 34d4621 into master Apr 2, 2026
1 check passed

halotukozak deleted the docs/kdoc branch April 2, 2026 14:21

halotukozak added this to the 0.0.2 milestone Apr 2, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add KDoc generation for properties, enum constants, and endpoints#32

feat: add KDoc generation for properties, enum constants, and endpoints#32
halotukozak merged 14 commits intomasterfrom
docs/kdoc

halotukozak commented Mar 25, 2026

Uh oh!

github-actions bot commented Mar 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

janwawszczak left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janwawszczak left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

halotukozak commented Mar 25, 2026

Summary

Test plan

Uh oh!

github-actions bot commented Mar 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

janwawszczak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

janwawszczak left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Mar 25, 2026 •

edited

Loading