atharvalade opened a new pull request, #2711:
URL: https://github.com/apache/iggy/pull/2711
## Which issue does this PR close?
Closes #2231
## Rationale
The async client had minimal documentation — interfaces lacked JavaDoc,
there was no usage guide, and developers had no reference for CompletableFuture
patterns, error handling, or migration from the blocking client.
## What changed?
The async client interfaces (`StreamsClient`, `MessagesClient`,
`TopicsClient`, `UsersClient`, `ConsumerGroupsClient`) and `AsyncIggyTcpClient`
had sparse or missing JavaDoc. Developers had to read the source to understand
method contracts, parameter semantics, and exception behavior.
Added comprehensive JavaDoc to all public async APIs with `@param`,
`@return`, `@throws`, and `@see` cross-references. Created `ASYNC_CLIENT.md`
covering getting started, connection management, error handling,
CompletableFuture chaining patterns, three example applications
(high-throughput producer, backpressure consumer, error recovery), performance
characteristics (async vs blocking, thread pool sizing), and a step-by-step
migration guide. Added `package-info.java` for both async packages.
## Local Execution
- Passed`compileJava`, `checkstyleMain`, `spotlessCheck`, and `javadoc` all
pass with zero errors
- Pre-commit hooks not ran `prek` is Rust-specific, this PR is Java/docs only
## AI Usage
1. Claude (Opus 4.6) via Cursor IDE
2. The documentation content is AI-generated. Used AI to write JavaDoc, the
ASYNC_CLIENT.md guide, and example code snippets. Also used AI to
cross-reference every `{@link}`, `@see`, and `@throws` tag against the actual
source code, and to verify all code examples in the guide use correct method
signatures, return types, and accessor names from the real API.
3. Verified by running a clean build from scratch (`clean` + `compileJava` +
`checkstyleMain` + `spotlessCheck` + `javadoc`) all pass. Manually audited
every JavaDoc reference against the source (e.g., confirmed
`CompressionAlgorithm.None` is an enum constant not a method, confirmed record
accessors like `stream.id()` and `polled.messages()` match actual field names,
confirmed all 11 exception types in the error handling table exist in the
hierarchy).
4. Yes
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
