docs(server): deprecated bind_connection, note about Connection's Opaque item

Author: seanmonstar

src/server/mod.rs

@@ -105,6 +105,16 @@ pub struct AddrIncoming {
 /// A future binding a connection with a Service.
 ///
 /// Polling this future will drive HTTP forward.
+///
+/// # Note
+///
+/// This will currently yield an unnameable (`Opaque`) value
+/// on success. The purpose of this is that nothing can be assumed about
+/// the type, not even it's name. It's probable that in a later release,
+/// this future yields the underlying IO object, which could be done without
+/// a breaking change.
+///
+/// It is likely best to just map the value to `()`, for now.
 #[must_use = "futures do nothing unless polled"]
 pub struct Connection<I, S>
 where

src/server/server_proto.rs

@@ -30,17 +30,10 @@ impl<B: AsRef<[u8]> + 'static> Http<B> {
     /// Use this `Http` instance to create a new server task which handles the
     /// connection `io` provided.
     ///
-    /// This is the low-level method used to actually spawn handling a TCP
-    /// connection, typically. The `handle` provided is the event loop on which
-    /// the server task will be spawned, `io` is the I/O object associated with
-    /// this connection (data that's read/written), `remote_addr` is the remote
-    /// peer address of the HTTP client, and `service` defines how HTTP requests
-    /// will be handled (and mapped to responses).
+    /// # Deprecated
     ///
-    /// This method is typically not invoked directly but is rather transitively
-    /// used through [`bind`](#method.bind). This can be useful,
-    /// however, when writing mocks or accepting sockets from a non-TCP
-    /// location.
+    /// This method is deprecated. If seeking a replacement, consider
+    /// `Http::serve_connection`.
     pub fn bind_connection<S, I, Bd>(&self,
                                  handle: &Handle,
                                  io: I,