[Aaron ("AJ") Steers (aaronsteers)]

What

Adds comprehensive KDoc documentation to three core Kotlin Bulk CDK interfaces that are directly used by destination connector developers:

• DestinationWriter - Main entry point for destination connectors
• StreamLoader - Per-stream loading lifecycle handler
• TableOperationsClient - Database-agnostic table operations interface

This documentation will help connector developers understand the public-facing APIs and will eventually render into auto-generated KDoc documentation.

Related to the broader effort to improve CDK documentation for both LLM consumers and human contributors. Python CDK documentation was completed in airbytehq/airbyte-python-cdk#852.

How

• Replaced minimal inline comments with comprehensive KDoc documentation
• Added interface-level documentation explaining purpose, usage patterns, and relationships to other components
• Added method-level documentation with @param and @return tags where appropriate
• Documented lifecycle ordering (e.g., setup → createStreamLoader → teardown)
• Applied ktlint formatting to satisfy line length and spacing requirements

Review guide

Critical items to verify:

1. DestinationWriter.kt - Verify the documented lifecycle order (setup → createStreamLoader → teardown) matches actual framework behavior
2. StreamLoader.kt - Confirm the relationship between close() and teardown() is accurately described. The original code had a comment that "hadNonzeroRecords is only used by legacy typing and deduping" - I removed this in favor of a more general description. Please verify this is correct.
3. TableOperationsClient.kt - Validate that operation descriptions match actual database behavior, especially:
   • overwriteTable - Does it truly atomically replace and drop the source table?
   • copyTable - Is it really INSERT without deduplication?
   • upsertTable - Does it handle primary keys as described?

Documentation accuracy concerns:

• The documentation describes inferred behavior based on method signatures and context. Please verify against actual implementation details and known usage patterns.
• Check if any important edge cases, gotchas, or implementation notes are missing.

User Impact

Connector developers will have better documentation when implementing destination connectors using the Kotlin Bulk CDK. This documentation will eventually be published as auto-generated KDoc.

No functional changes - documentation only.

Can this PR be safely reverted and rolled back?

• YES 💚

---

Requested by: AJ Steers (Aaron ("AJ") Steers (@aaronsteers), aj@airbyte.io)
Session: https://app.devin.ai/sessions/714fb9c366844fd49a0196e61f99f639

[devin-ai-integration]

Original prompt from AJ Steers

Received message in Slack channel #ask-devin-ai:

@Devin - we need to improve our code documentation across Kotlin and Python CDKs. Let's do a first pass on the Kotlin source CDK and the Python CDK. From each CDK, pick two or three modules that are public facing, meaning they are leveraged directly by connectors, and let's add the minimum documentation needed to explain the code to an LLM that will need to write code that interfaces with it. For Python CDK, these comments will render into the automated PDOCs. For the Kotlin CDK, he should render into a new auto generated KT docs website that we are not building yet but we will soon. Interview me before we start to make sure we agree on the right level of documentation.
Thread URL: https://airbytehq-team.slack.com/archives/C08BHPUMEPJ/p1763579871483699

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[github-actions]

👋 Greetings, Airbyte Team Member!

Here are some helpful tips and reminders for your convenience.

Helpful Resources

• Breaking Changes Guide - Breaking changes, migration guides, and upgrade deadlines
• Developing Connectors Locally
• Managing Connector Secrets
• On-Demand Live Tests
• On-Demand Regression Tests
• #connector-ci-issues
• #connector-publish-updates
• #connector-build-statuses

PR Slash Commands

Airbyte Maintainers (that's you!) can execute the following slash commands on your PR:

• /format-fix - Fixes most formatting issues.
• /bump-version - Bumps connector versions.
  • You can specify a custom changelog by passing changelog. Example: /bump-version changelog="My cool update"
  • Leaving the changelog arg blank will auto-populate the changelog from the PR title.
• /run-cat-tests - Runs legacy CAT tests (Connector Acceptance Tests)
• /build-connector-images - Builds and publishes a pre-release docker image for the modified connector(s).
• JVM connectors:
  • /update-connector-cdk-version connector=<CONNECTOR_NAME> - Updates the specified connector to the latest CDK version.
    Example: /update-connector-cdk-version connector=destination-bigquery
  • /bump-bulk-cdk-version bump=patch changelog='foo' - Bump the Bulk CDK's version. bump can be major/minor/patch.
• Python connectors:
  • /poe connector source-example lock - Run the Poe lock task on the source-example connector, committing the results back to the branch.
  • /poe source example lock - Alias for /poe connector source-example lock.
  • /poe source example use-cdk-branch my/branch - Pin the source-example CDK reference to the branch name specified.
  • /poe source example use-cdk-latest - Update the source-example CDK dependency to the latest available version.

📝 Edit this welcome message.

[devin-ai-integration]

/format-fix

[github-actions]

Deploy preview for airbyte-kotlin-cdk ready!

✅ Preview
https://airbyte-kotlin-8p59ybf1a-airbyte-growth.vercel.app

Built with commit 5b054fc.
This pull request is being automatically deployed with vercel-action

[Ryan Br... (tryangul)]

The interfaces are misleading and have tricked devin. Given we're in the process of refactoring everything, I'd hold off on comment churn until we've settled things.

[Aaron ("AJ") Steers (aaronsteers)]

Ryan Br... (@tryangul)

The interfaces are misleading and have tricked devin. Given we're in the process of refactoring everything, I'd hold off on comment churn until we've settled things.

Totally okay. Plan was not to merge this directly but to see how close Devin would get with zero manually-injected context - and at some point do a mob-coding fix-up to whatever Devin guessed wrong. Now that automated CDK docs are live at https://airbyte-kotlin-cdk.vercel.app, all subsequent inline docs improvements will land there in the auto generated API docs.

[Aaron ("AJ") Steers (aaronsteers)]

Closing for now. We can re-open or start fresh. Also - confirmed above that the new CDK docs Vercel preview builds appear to be working correctly.