docs: simplify redundant KDoc across the SDK surface (#210)

PR: #210

Author: OmarAlJarrah

sdk-async-reactor/src/main/kotlin/org/dexpace/sdk/async/reactor/Reactor.kt

@@ -59,18 +59,10 @@ public fun AsyncHttpClient.executeMono(
 ): Mono<Response> = deferMono { executeAsync(request, options) }
 
 /**
- * Pipeline-level [Mono] facade — see [executeMono].
- *
- * ## MDC propagation
- *
- * The SLF4J MDC is captured **per subscription**, not at assembly time: the [Mono.defer]
- * wrapper snapshots MDC the moment a subscriber subscribes, so each subscription reinstates
- * the *subscriber's* `trace.id` / `span.id` — both in the [AsyncHttpPipeline.sendAsync]
- * supplier and in the adapter's own `.doOnSubscribe` / `.doOnCancel` hooks, even when those
- * fire on a different scheduler. A `Mono` assembled once and re-subscribed therefore picks
- * up the MDC live at each subscribe, not a stale snapshot from the assembling thread.
- * To extend MDC propagation through user-supplied downstream operators, enable
- * `Hooks.enableAutomaticContextPropagation()` at the application level.
+ * Pipeline-level [Mono] facade — see [executeMono]. Same cold-publisher and
+ * per-subscription MDC semantics: each subscription reinstates the subscriber's
+ * `trace.id` / `span.id` for the [AsyncHttpPipeline.sendAsync] supplier and the
+ * `.doOnSubscribe` / `.doOnCancel` hooks.
  */
 public fun AsyncHttpPipeline.sendMono(request: Request): Mono<Response> = deferMono { sendAsync(request) }
 

sdk-core/src/main/kotlin/org/dexpace/sdk/core/auth/AuthChallengeParser.kt

@@ -24,8 +24,7 @@ import java.util.Locale
  * delimiters. Escape sequences (`\"`, `\\`) inside quoted strings are unescaped on
  * read; surrounding quotes are stripped from the stored value.
  *
- * Malformed challenges are skipped — the parser does not throw on bad input. This
- * matches the [edge-case guardrails][to-implement.md] for Rank 12.
+ * Malformed challenges are skipped — the parser does not throw on bad input.
  */
 public object AuthChallengeParser {
     // Initial capacity for the per-challenge auth-param map. Auth challenges typically

sdk-core/src/main/kotlin/org/dexpace/sdk/core/auth/AuthRequirement.kt

@@ -11,8 +11,8 @@ import org.dexpace.sdk.core.generics.Builder as GenericBuilder
 
 /**
  * A single auth alternative an operation accepts: one [AuthScheme] plus any OAuth-specific
- * parameters ([oauthScopes] / [oauthParams]) the auth step should forward to the token
- * provider when the chosen scheme is [AuthScheme.OAUTH2].
+ * parameters ([oauthScopes] / [oauthParams], e.g. `claims`) the auth step should forward to
+ * the token provider when the chosen scheme is [AuthScheme.OAUTH2].
  *
  * Each requirement pairs a scheme with its *own* OAuth parameters, so an operation that
  * accepts OAuth with `read` scopes **or** a static API key is two requirements, only one of
@@ -27,10 +27,6 @@ import org.dexpace.sdk.core.generics.Builder as GenericBuilder
  * copy), so a caller that retains and later mutates the argument collection cannot mutate this
  * instance.
  * Instances are obtained via [of] or [Builder], never a public constructor.
- *
- * @param scheme the auth scheme this alternative selects.
- * @param oauthScopes OAuth scopes to forward to the token provider; ignored for non-OAuth schemes.
- * @param oauthParams extra OAuth params to forward (e.g. `claims`); ignored for non-OAuth schemes.
  */
 public class AuthRequirement private constructor(
     scheme: AuthScheme,

sdk-core/src/main/kotlin/org/dexpace/sdk/core/auth/BearerToken.kt

@@ -18,8 +18,8 @@ import java.time.Instant
  * pre-emptively refresh by passing a `marginBefore` to [isExpiredAt] — useful for avoiding
  * mid-flight expiries during long requests.
  *
- * Value semantics via `data class` so equal tokens compare equal and can be diffed by
- * tests cheaply.
+ * Value semantics via `data class` gives value-based [equals]/[hashCode], so tokens diff
+ * cheaply in tests.
  *
  * @param token the bearer token string; must not be blank.
  * @param expiresAt the instant the token becomes invalid, or null for a non-expiring token.

sdk-core/src/main/kotlin/org/dexpace/sdk/core/auth/DigestChallengeHandler.kt

@@ -95,12 +95,9 @@ public class DigestChallengeHandler
          *   absent (legacy RFC 2069 style — we'll still handle it),
          * - it carries a `realm` and `nonce`.
          *
-         * Ordering: we scan [preferredAlgorithms] first, then within that scan the
-         * candidates. This ensures SHA-256 wins over MD5 even when MD5 appears first
-         * in the header.
-         *
-         * Per-challenge validation is delegated to [toCandidate]; this scan only applies
-         * the algorithm-priority ordering, independent of the order challenges arrived in.
+         * Per-challenge validation is delegated to [toCandidate]. This scan then applies
+         * the [preferredAlgorithms] priority ordering — independent of the order challenges
+         * arrived in — so SHA-256 wins over MD5 even when MD5 appears first in the header.
          */
         private fun pickChallenge(
             challenges: List<AuthenticateChallenge>,

sdk-core/src/main/kotlin/org/dexpace/sdk/core/client/HttpClient.kt

@@ -73,10 +73,9 @@ public fun interface HttpClient : AutoCloseable {
     ): Response = execute(request)
 
     /**
-     * Releases any resources held by this transport. The default implementation is a no-op so
-     * SAM literals and lightweight client wrappers do not need to implement [AutoCloseable.close]
-     * explicitly. Transport implementations that own background threads, connection pools, or
-     * executors must override this method; see the class-level "Lifecycle" KDoc for the contract.
+     * Releases any resources held by this transport. The default is a no-op (so SAM literals and
+     * lightweight wrappers need not implement it); transports that own threads, pools, or executors
+     * must override it — see the class-level "Lifecycle" KDoc for the contract.
      */
     public override fun close() {
         // No-op default. Transports with owned resources override this.

sdk-core/src/main/kotlin/org/dexpace/sdk/core/generics/BuilderChecks.kt

@@ -30,8 +30,6 @@ package org.dexpace.sdk.core.generics
  * across builders with this helper keeps the missing-field diagnostics identical, which
  * matters most once builders are emitted by codegen.
  *
- * @param name The field name to report in the failure message.
- * @param value The field value to validate.
  * @return [value], guaranteed non-null.
  * @throws IllegalStateException If [value] is `null`.
  */

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/common/Headers.kt

@@ -38,7 +38,6 @@ public data class Headers private constructor(
      * Returns the first header value for the given name, or null if none.
      *
      * @param name the header name (case-insensitive)
-     * @return the first header value, or null if not found
      */
     public fun get(name: String): String? = headersMap[sanitizeName(name)]?.firstOrNull()
 
@@ -71,24 +70,19 @@ public data class Headers private constructor(
     public fun contains(name: HttpHeaderName): Boolean = headersMap.containsKey(name.caseInsensitiveName)
 
     /**
-     * Returns a point-in-time snapshot of all header names at the time of the call.
+     * Returns a snapshot of all header names.
      *
-     * Returns a defensive copy (`Set<String>`) so that callers cannot observe later
-     * mutations to this [Headers] instance through the returned set. The set is exposed
-     * through Kotlin's read-only [Set] type.
-     *
-     * @return a snapshot of header names
+     * A defensive copy (`Set<String>`) exposed through Kotlin's read-only [Set] type, so
+     * callers cannot observe later mutations to this [Headers] instance through it.
      */
     public fun names(): Set<String> = headersMap.keys.toSet()
 
     /**
-     * Returns a point-in-time snapshot of all header entries at the time of the call.
+     * Returns a snapshot of all header entries.
      *
      * Each entry is copied into a fresh map so that callers cannot observe later mutations
      * to this [Headers] instance through the returned set. The set and its per-name value
      * lists are exposed through Kotlin's read-only [Set] / [List] types.
-     *
-     * @return a snapshot of header entries as [Map.Entry]
      */
     public fun entries(): Set<Map.Entry<String, List<String>>> {
         val snapshot = LinkedHashMap<String, List<String>>(headersMap.size)
@@ -98,11 +92,7 @@ public data class Headers private constructor(
         return snapshot.entries
     }
 
-    /**
-     * Returns a new [Builder] initialized with the existing headers.
-     *
-     * @return a new [Builder]
-     */
+    /** Returns a new [Builder] initialized with the existing headers. */
     public fun newBuilder(): Builder = Builder(this)
 
     override fun toString(): String = headersMap.toString()
@@ -120,8 +110,6 @@ public data class Headers private constructor(
 
         /**
          * Creates a new builder initialized with the headers from [headers].
-         *
-         * @param headers the headers to initialize from
          */
         public constructor(headers: Headers) : this() {
             headers.headersMap.forEach { (key, values) ->
@@ -132,10 +120,6 @@ public data class Headers private constructor(
         /**
          * Adds a header with the specified name and value.
          * Multiple headers with the same name are allowed.
-         *
-         * @param name the header name
-         * @param value the header value
-         * @return this builder
          */
         public fun add(
             name: String,
@@ -144,10 +128,6 @@ public data class Headers private constructor(
 
         /**
          * Adds all header values for the specified name.
-         *
-         * @param name the header name
-         * @param values the list of header values
-         * @return this builder
          */
         public fun add(
             name: String,
@@ -175,7 +155,6 @@ public data class Headers private constructor(
          *
          * @param name the header name
          * @param value the header value, which may contain non-ASCII bytes
-         * @return this builder
          * @throws IllegalArgumentException if [name] is blank or contains a control/non-ASCII byte,
          *   or [value] contains a prohibited control character
          */
@@ -213,10 +192,6 @@ public data class Headers private constructor(
          * Sets the header with the specified name to the single value provided.
          * If headers with this name already exist, they are removed. Passing a `null`
          * [value] removes the header entirely (Azure / OkHttp semantics).
-         *
-         * @param name the header name
-         * @param value the header value, or `null` to remove
-         * @return this builder
          */
         public fun set(
             name: String,
@@ -233,10 +208,6 @@ public data class Headers private constructor(
         /**
          * Sets the header with the specified name to the values list provided.
          * If headers with this name already exist, they are removed.
-         *
-         * @param name the header name
-         * @param values the header values
-         * @return this builder
          */
         public fun set(
             name: String,
@@ -278,9 +249,6 @@ public data class Headers private constructor(
 
         /**
          * Removes any header with the specified name.
-         *
-         * @param name the header name
-         * @return this builder
          */
         public fun remove(name: String): Builder =
             apply {
@@ -309,11 +277,7 @@ public data class Headers private constructor(
                 }
             }
 
-        /**
-         * Builds an immutable [Headers] instance.
-         *
-         * @return the built [Headers]
-         */
+        /** Builds an immutable [Headers] instance. */
         public fun build(): Headers {
             // Deep, defensive copy: snapshot each value list into its own fresh copy so
             // that later builder mutations cannot reach into the built instance. The

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/common/HttpRange.kt

@@ -78,13 +78,8 @@ public class HttpRange private constructor(private val raw: String) {
         }
 
         /**
-         * Parses a `Range` header value into an [HttpRange]. The accepted value is stored
-         * verbatim and round-trips through [toHeaderValue] unchanged, so its exact casing is
-         * preserved on the wire.
-         *
-         * The value must begin with the `bytes=` unit token (matched case-insensitively, with no
-         * leading whitespace); only the `bytes` unit is accepted, and multi-range values are
-         * rejected.
+         * Parses a `Range` header value into an [HttpRange], storing it verbatim so its casing
+         * round-trips through [toHeaderValue] (see the class KDoc for the accepted-form contract).
          *
          * @throws IllegalArgumentException if the value does not begin with the `bytes=` unit
          *   token or contains a comma (multi-range).

sdk-core/src/main/kotlin/org/dexpace/sdk/core/http/common/MediaType.kt

@@ -71,9 +71,9 @@ public data class MediaType private constructor(
      * in a try/catch.
      *
      * The lookup is case-insensitive: `UTF-8`, `utf-8`, and `Utf-8` all resolve to the same
-     * [Charset]. The parameter value is lower-cased before being passed to [Charset.forName],
-     * normalising the cache key. The JDK accepts any case, but lowercasing here ensures a
-     * consistent canonical form for comparison and logging purposes.
+     * [Charset]. The value is lower-cased before [Charset.forName] — the JDK accepts any case,
+     * but a canonical lower-case form normalises the cache key and keeps comparison and logging
+     * consistent.
      */
     val charset: Charset?
         get() =
@@ -222,7 +222,6 @@ public data class MediaType private constructor(
          * Parses a media type string into a [MediaType].
          *
          * @param mediaType the wire-form value (e.g. `application/json;charset=utf-8`).
-         * @return the parsed [MediaType].
          * @throws IllegalArgumentException if the media type cannot be parsed.
          */
         @JvmStatic