diff --git a/akka-http-core/src/main/java/akka/http/javadsl/HttpsContext.java b/akka-http-core/src/main/java/akka/http/javadsl/HttpsContext.java
index 7bbf06710a..dbe39054a4 100644
--- a/akka-http-core/src/main/java/akka/http/javadsl/HttpsContext.java
+++ b/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();
diff --git a/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala b/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala
index 6a6c2f63b4..d6c4f9870f 100644
--- a/akka-http-core/src/main/scala/akka/http/scaladsl/Http.scala
+++ b/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,
@@ -777,4 +783,4 @@ trait DefaultSSLContextCreation {
     HttpsContext(sslContext, sslParameters = Some(defaultParams))
   }
 
-}
\ No newline at end of file
+}
diff --git a/akka-stream/src/main/scala/akka/stream/io/SslTls.scala b/akka-stream/src/main/scala/akka/stream/io/SslTls.scala
index 3f7b5d2c16..6982548e6a 100644
--- a/akka-stream/src/main/scala/akka/stream/io/SslTls.scala
+++ b/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]],