docs: simplify redundant KDoc across the SDK surface#210
Merged
Conversation
Trim docstring boilerplate that restated the code without adding information, and de-duplicate rationale that was copy-pasted across overloads. Comments only — no behavioral or API changes. - Collapse fluent builder-setter KDoc to one-line summaries: drop "@return This builder." and @param tags that only echoed the parameter name. Where a tag carried a real fact (a nullability note, an example value, a constraint, a @throws), fold it into the summary rather than dropping it. This brings the Response, Request, Headers, and IdempotencyKeyStep builders in line with the terse setter style the transport and options builders already use. - De-duplicate rationale repeated verbatim across sibling overloads (ClientLogger.at*, the Reactor/AsyncHttpPipeline send/execute pairs, the proxy-resolution source list) down to one canonical copy plus a cross-reference. - Remove facts stated two or three times within a single file, e.g. HttpException/NetworkException retryability and RequestRecoveryChain exception semantics. - Drop a stale reference to an internal planning file from the AuthChallengeParser KDoc. Deliberately preserved the SDK's design rationale (cancellation, thread-safety, equality, and spec-citation notes); the goal was to cut words, not information. Net ~360 fewer lines across 49 files.
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
1 participant
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.
What
Simplifies redundant KDoc across the SDK. This is a comments-only change — no
behavioral or API changes (the binary-compatibility snapshots are untouched).
Most of the SDK's docstrings are in good shape and carry genuine design
rationale. The noise that had accumulated was mechanical and concentrated,
mostly in fluent builders.
Changes
@return This builder.tag and
@paramtags that only echoed the parameter name, on top of a one-linesummary that already said everything. Collapsed these to one-line summaries.
Where a tag carried a real fact (a nullability note, an example value, a
constraint, a
@throws), the fact is folded into the summary rather thandropped. Brings the
Response,Request,Headers, andIdempotencyKeyStepbuilders in line with the terse setter style the transport and options builders
already use.
sibling overloads (
ClientLogger.at*, theReactor/AsyncHttpPipelinesend/execute pairs, the proxy-resolution source list) are reduced to one
canonical copy plus a cross-reference.
HttpException/NetworkExceptionretryability,
RequestRecoveryChainexception semantics) are stated once.AuthChallengeParserKDoc.What was deliberately kept
The SDK's design rationale — cancellation, thread-safety, equality, and
concurrency contracts, and RFC/WHATWG/JEP citations — is preserved. The goal was
to cut words, not information. Every
@throwswas kept.Size
~360 fewer lines across 49 files.
Validation
compileKotlin,ktlint, anddetektpass on the affected modules(
sdk-core,sdk-transport-jdkhttp,sdk-async-reactor,sdk-serde-jackson).