Docs for connectors

2 files changed, 42 insertions, 0 deletions

diff --git a/openssl/src/ssl/connector.rs b/openssl/src/ssl/connector.rs
index 62f0a284..da2c03df 100644
--- a/openssl/src/ssl/connector.rs
+++ b/openssl/src/ssl/connector.rs
@@ -40,9 +40,13 @@ fn ctx(method: SslMethod) -> Result<SslContextBuilder, ErrorStack> {
     Ok(ctx)
 }
 
+/// A builder for `ClientConnector`s.
 pub struct ClientConnectorBuilder(SslContextBuilder);
 
 impl ClientConnectorBuilder {
+    /// Creates a new builder for TLS connections.
+    ///
+    /// The default configuration is based off of libcurl's and is subject to change.
     pub fn tls() -> Result<ClientConnectorBuilder, ErrorStack> {
         ClientConnectorBuilder::new(SslMethod::tls())
     }
@@ -55,22 +59,35 @@ impl ClientConnectorBuilder {
         Ok(ClientConnectorBuilder(ctx))
     }
 
+    /// Returns a shared reference to the inner `SslContextBuilder`.
     pub fn context(&self) -> &SslContextBuilder {
         &self.0
     }
 
+    /// Returns a mutable reference to the inner `SslContextBuilder`.
     pub fn context_mut(&mut self) -> &mut SslContextBuilder {
         &mut self.0
     }
 
+    /// Consumes the builder, returning a `ClientConnector`.
     pub fn build(self) -> ClientConnector {
         ClientConnector(self.0.build())
     }
 }
 
+/// A type which wraps client-side streams in a TLS session.
+///
+/// OpenSSL's default configuration is highly insecure. This connector manages the OpenSSL
+/// structures, configuring cipher suites, session options, hostname verification, and more.
+///
+/// OpenSSL's built in hostname verification is used when linking against OpenSSL 1.0.2 or 1.1.0,
+/// and a custom implementation is used when linking against OpenSSL 1.0.1.
 pub struct ClientConnector(SslContext);
 
 impl ClientConnector {
+    /// Initiates a client-side TLS session on a stream.
+    ///
+    /// The domain is used for SNI and hostname verification.
     pub fn connect<S>(&self, domain: &str, stream: S) -> Result<SslStream<S>, HandshakeError<S>>
         where S: Read + Write
     {
@@ -82,9 +99,14 @@ impl ClientConnector {
     }
 }
 
+/// A builder for `ServerConnector`s.
 pub struct ServerConnectorBuilder(SslContextBuilder);
 
 impl ServerConnectorBuilder {
+    /// Creates a new builder for server-side TLS connections.
+    ///
+    /// The default configuration is based off of the intermediate profile of Mozilla's SSL
+    /// Configuration Generator, and is subject to change.
     pub fn tls<I, T>(private_key: &PKeyRef,
                      certificate: &X509Ref,
                      chain: I)
@@ -127,22 +149,30 @@ impl ServerConnectorBuilder {
         Ok(ServerConnectorBuilder(ctx))
     }
 
+    /// Returns a shared reference to the inner `SslContextBuilder`.
     pub fn context(&self) -> &SslContextBuilder {
         &self.0
     }
 
+    /// Returns a mutable reference to the inner `SslContextBuilder`.
     pub fn context_mut(&mut self) -> &mut SslContextBuilder {
         &mut self.0
     }
 
+    /// Consumes the builder, returning a `ServerConnector`.
     pub fn build(self) -> ServerConnector {
         ServerConnector(self.0.build())
     }
 }
 
+/// A type which wraps server-side streams in a TLS session.
+///
+/// OpenSSL's default configuration is highly insecure. This connector manages the OpenSSL
+/// structures, configuring cipher suites, session options, and more.
 pub struct ServerConnector(SslContext);
 
 impl ServerConnector {
+    /// Initiates a server-side TLS session on a stream.
     pub fn connect<S>(&self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>
         where S: Read + Write
     {
diff --git a/openssl/src/ssl/mod.rs b/openssl/src/ssl/mod.rs
index 9e39d8bf..ddf27460 100644
--- a/openssl/src/ssl/mod.rs
+++ b/openssl/src/ssl/mod.rs
@@ -342,6 +342,7 @@ pub enum SniError {
     NoAck,
 }
 
+/// A builder for `SslContext`s.
 pub struct SslContextBuilder(*mut ffi::SSL_CTX);
 
 impl Drop for SslContextBuilder {
@@ -793,6 +794,7 @@ impl SslCipherRef {
     }
 }
 
+/// A reference to an `Ssl`.
 pub struct SslRef(Opaque);
 
 unsafe impl Send for SslRef {}
@@ -1104,6 +1106,11 @@ impl Ssl {
     }
 
     /// Creates an SSL/TLS client operating over the provided stream.
+    ///
+    /// # Warning
+    ///
+    /// OpenSSL's default configuration is insecure. It is highly recommended to use
+    /// `ClientConnector` rather than `Ssl` directly, as it manages that configuration.
     pub fn connect<S>(self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>
         where S: Read + Write
     {
@@ -1131,6 +1138,11 @@ impl Ssl {
     }
 
     /// Creates an SSL/TLS server operating over the provided stream.
+    ///
+    /// # Warning
+    ///
+    /// OpenSSL's default configuration is insecure. It is highly recommended to use
+    /// `ServerConnector` rather than `Ssl` directly, as it manages that configuration.
     pub fn accept<S>(self, stream: S) -> Result<SslStream<S>, HandshakeError<S>>
         where S: Read + Write
     {