From 04df97c6c95d25a2ed85b5415d21f1414f76694c Mon Sep 17 00:00:00 2001
From: Raman Gupta <rocketraman@gmail.com>
Date: Tue, 23 Jan 2024 10:56:34 -0500
Subject: [PATCH] Update TLS.kt with docs about coroutineContext parameter
 (#3952)

Update docs based on discussion in Slack: https://kotlinlang.slack.com/archives/C0A974TJ9/p1705535602239209.

(cherry picked from commit 6d02e21508523758fdc3c35b403143706d13253a)
---
 .../jvm/src/io/ktor/network/tls/TLS.kt        | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/ktor-network/ktor-network-tls/jvm/src/io/ktor/network/tls/TLS.kt b/ktor-network/ktor-network-tls/jvm/src/io/ktor/network/tls/TLS.kt
index d6df5d2eb4b..e43d23b43bd 100644
--- a/ktor-network/ktor-network-tls/jvm/src/io/ktor/network/tls/TLS.kt
+++ b/ktor-network/ktor-network-tls/jvm/src/io/ktor/network/tls/TLS.kt
@@ -11,6 +11,13 @@ import kotlin.coroutines.*
 
 /**
  * Make [Socket] connection secure with TLS using [TLSConfig].
+ *
+ * The coroutine context passed here will receive errors when there are no other handlers to process it (for example,
+ * in case of a shutdown during a TLS handshake). The context may also be used for cancellation.
+ *
+ * Note that the context passed here is rarely a child of the scope in which the method is called, because it is not
+ * usually a decomposition of the parent task. If it is a child, errors may be propogated to the parent's coroutine
+ * exception handler rather than being caught and handled via a try-catch block.
  */
 public actual suspend fun Socket.tls(
     coroutineContext: CoroutineContext,
@@ -31,6 +38,13 @@ public actual suspend fun Socket.tls(
 
 /**
  * Make [Socket] connection secure with TLS.
+ *
+ * The coroutine context passed here will receive errors when there are no other handlers to process it (for example,
+ * in case of a shutdown during a TLS handshake). The context may also be used for cancellation.
+ *
+ * Note that the context passed here is rarely a child of the scope in which the method is called, because it is not
+ * usually a decomposition of the parent task. If it is a child, errors may be propogated to the parent's coroutine
+ * exception handler rather than being caught and handled via a try-catch block.
  */
 public suspend fun Socket.tls(
     coroutineContext: CoroutineContext,
@@ -47,6 +61,13 @@ public suspend fun Socket.tls(
 
 /**
  * Make [Socket] connection secure with TLS configured with [block].
+ *
+ * The coroutine context passed here will receive errors when there are no other handlers to process it (for example,
+ * in case of a shutdown during a TLS handshake). The context may also be used for cancellation.
+ *
+ * Note that the context passed here is rarely a child of the scope in which the method is called, because it is not
+ * usually a decomposition of the parent task. If it is a child, errors may be propogated to the parent's coroutine
+ * exception handler rather than being caught and handled via a try-catch block.
  */
 public actual suspend fun Socket.tls(coroutineContext: CoroutineContext, block: TLSConfigBuilder.() -> Unit): Socket =
     tls(coroutineContext, TLSConfigBuilder().apply(block).build())