Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refactor documentation for Java Records and Kotlin Data Classes #2932

Draft
wants to merge 1 commit into
base: 4.8.x
Choose a base branch
from

Conversation

wetted
Copy link
Contributor

@wetted wetted commented May 3, 2024

closes #2896

@timyates @sdelamo see what you think about this. It is in draft and can use some cleanup, but I'd like feedback on this approach:

This is meant to solve two problems:

  1. The Java Records documentation uses code snippets; however, there was only code in docs-examples for Java. If a user selects a Kotlin or Groovy tab for snippets in the documentation, then nothing at all shows for the examples in the Java Records section (as reported in the issue linked from this PR).
  2. The Kotlin Data Classes section uses an asciidoc embedded code example. We want to avoid using those because we don't really know if they compile, and they have no tests to confirm they actually work.

I have taken an approach to unify the documentation for using Java Records and Kotlin Data Classes (and use POGOs for Groovy). This has the benefit – I think – that users can see inline the differences using Java records, Kotlin data classes, and Groovy POGOs.

The original Java Records example has a lot more code examples, but they are not used as snippets in the documentation. I left them as is, but did not create Kotlin and Groovy versions. I can do that if we want to be completely consistent across the docs-examples for all three languages.

…sure asciidoc snippets have examples for all languages, and to eliminate embedded code in asciidoc (that is not compiled and untested).

closes #2896
@wetted wetted requested review from timyates and sdelamo May 3, 2024 16:31
@wetted wetted self-assigned this May 3, 2024
Copy link

sonarcloud bot commented May 3, 2024

Quality Gate Passed Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
No open projects
Status: Ready for Review
Development

Successfully merging this pull request may close these issues.

Documentation section 6.5.13 is missing source code snippet
1 participant