feat: add KDoc generation for properties, enum constants, and endpoints#32
Open
halotukozak wants to merge 6 commits intomasterfrom
Open
feat: add KDoc generation for properties, enum constants, and endpoints#32halotukozak wants to merge 6 commits intomasterfrom
halotukozak wants to merge 6 commits intomasterfrom
Conversation
- 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>
Coverage Report
|
Contributor
There was a problem hiding this comment.
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.descriptionandEnumModel.valueDescriptions. - Parse
operation.descriptionandx-enum-descriptionsinto 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
Outdated
Show resolved
Hide resolved
core/src/main/kotlin/com/avsystem/justworks/core/gen/ClientGenerator.kt
Outdated
Show resolved
Hide resolved
core/src/main/kotlin/com/avsystem/justworks/core/gen/ClientGenerator.kt
Outdated
Show resolved
Hide resolved
core/src/main/kotlin/com/avsystem/justworks/core/gen/ModelGenerator.kt
Outdated
Show resolved
Hide resolved
- 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.
Contributor
There was a problem hiding this comment.
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.
Comment on lines
18
to
26
| data class Endpoint( | ||
| val path: String, | ||
| val method: HttpMethod, | ||
| val operationId: String, | ||
| val summary: String?, | ||
| val description: String? = null, | ||
| val tags: List<String>, | ||
| val parameters: List<Parameter>, | ||
| val requestBody: RequestBody?, |
There was a problem hiding this comment.
Adding description to the Endpoint primary constructor changes the public constructor signature and is a binary-breaking change for any downstream code compiled against the previous version. If this module is published/consumed as a library, consider providing a secondary constructor matching the old signature (delegating to the new one) or ensuring the release/versioning strategy accounts for the break.
…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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
descriptionfield toEndpoint,valueDescriptionstoEnumModeloperation.descriptionandx-enum-descriptionsModelGeneratoradds KDoc to properties with descriptions and per-constant KDoc fromvalueDescriptionsClientGeneratorgenerates KDoc with summary/description/@param/@returnfor endpointsTest plan
valueDescriptions🤖 Generated with Claude Code