add-java-code-snippets-in-docs

When to use

Adding Java code blocks alongside existing Kotlin blocks in mkdocs documentation (docs/docs/**.md). Typical triggers: "add Java examples to ", "add Java tabs", "complete the Java side of ", "fix the Java block in ".

Do NOT use this skill for:

• Writing brand-new Kotlin docs (no precursor Kotlin block to mirror).
• Splitting source files between JVM and non-JVM source sets — use the split-jvm-nonjvm skill instead.
• Java examples outside the mkdocs/Knit pipeline.

Prerequisites

JDK 17. Gradle 8.x fails cryptically on newer JDKs. If the default JDK is newer, prefix every ./gradlew command in this workflow with JAVA_HOME=/path/to/jdk-17.

Before starting

Read one reference doc to anchor on the established pattern:

• docs/docs/features/tracing.md — full Tracing feature (blocks 1–6).
• docs/docs/agent-events.md — custom FeatureMessageProcessor subclass (suspend bridge methods handleMessage / handleClose).
• docs/docs/testing.md — MockPromptExecutor builder, tool mocking, comment-only blocks for Kotlin-only DSL.
• docs/docs/features/open-telemetry/index.md — OpenTelemetry examples.
• docs/docs/features/open-telemetry/opentelemetry-langfuse-exporter.md — Langfuse exporter.
• docs/docs/features/open-telemetry/opentelemetry-weave-exporter.md — Weave exporter.

Workflow

For each Kotlin code block in the target .md:

1. Read the Kotlin block: INCLUDE, visible code, SUFFIX, KNIT directive.
2. Check existing Java tab. If absent → add one. If it has empty /** */ placeholder content → replace entirely. If it has real content → update.
3. Consider Kotlin-side alignment. If the Kotlin block uses Kotlin-only APIs (kotlinx.io, MutableStateFlow, KLogger, inline Duration), consider whether the Kotlin example should switch to a JVM create() factory (e.g., TraceFeatureMessageFileWriter.create(path)). This keeps the two examples structurally aligned. See reference/factory-classes.md.
4. Add @JavaAPI bridge methods if missing. If the Java code needs a bridge that doesn't exist yet (e.g., a builder method on MockExecutorBuilder), add it before writing the Java tab. This may pause the doc work for a source-code change — flag it to the user before proceeding.
5. Write the Java tab immediately after the Kotlin tab, using the template below.
6. If renaming Knit files (e.g., hyphenated example-feature-java-01.java → camelCase exampleFeatureJava01.java), delete the old generated files first.
7. Generate and compile (see Verification at the bottom).
8. Read the generated .java to confirm correctness. Fix and repeat 7–8 on failure.