#19213 clarify clientAuth=None

akka-http-core/src/main/java/akka/http/javadsl/HttpsContext.java

@@ -15,6 +15,12 @@ import java.util.Optional;
 
 import scala.compat.java8.OptionConverters;
 
+/**
+ * TLS configuration for an HTTPS server binding or client connection.
+ * For the sslContext please refer to the com.typeasfe.ssl-config library.
+ * The remaining four parameters configure the initial session that will
+ * be negotiated, see {@link akka.stream.io.NegotiateNewSession} for details.
+ */
 public abstract class HttpsContext {
     
     public abstract SSLContext getSslContext();

akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala

@@ -712,6 +712,12 @@ object Http extends ExtensionId[HttpExt] with ExtensionIdProvider {
 import scala.collection.JavaConverters._
 
 //# https-context-impl
+/**
+ * TLS configuration for an HTTPS server binding or client connection.
+ * For the sslContext please refer to the com.typeasfe.ssl-config library.
+ * The remaining four parameters configure the initial session that will
+ * be negotiated, see [[akka.stream.io.NegotiateNewSession]] for details.
+ */
 final case class HttpsContext(sslContext: SSLContext,
                               enabledCipherSuites: Option[immutable.Seq[String]] = None,
                               enabledProtocols: Option[immutable.Seq[String]] = None,

akka-stream/src/main/scala/akka/stream/io/SslTls.scala

@@ -382,6 +382,10 @@ sealed trait SslTlsOutbound
  *  - `enabledProtocols` will be passed to `SSLEngine::setEnabledProtocols()`
  *  - `clientAuth` will be passed to `SSLEngine::setWantClientAuth()` or `SSLEngine.setNeedClientAuth()`, respectively
  *  - `sslParameters` will be passed to `SSLEngine::setSSLParameters()`
+ *
+ * Please note that passing `clientAuth = None` means that no change is done
+ * on client authentication requirements while `clientAuth = Some(ClientAuth.None)`
+ * switches off client authentication.
  */
 case class NegotiateNewSession(
   enabledCipherSuites: Option[immutable.Seq[String]],