Rollup merge of rust-lang#41499 - steveklabnik:gh25164, r=alexcrichton

Address platform-specific behavior in TcpStream::shutdown

Fixes rust-lang#25164

r? @rust-lang/libs from the GitHub thread, it seems like documenting this behavior is okay, but I want to make sure that's what you want.

Author: Ariel Ben-Yehuda

src/libstd/net/tcp.rs

@@ -177,6 +177,13 @@ impl TcpStream {
     ///
     /// [`Shutdown`]: ../../std/net/enum.Shutdown.html
     ///
+    /// # Platform-specific behavior
+    ///
+    /// Calling this function multiple times may result in different behavior,
+    /// depending on the operating system. On Linux, the second call will
+    /// return `Ok(())`, but on macOS, it will return `ErrorKind::NotConnected`.
+    /// This may change in the future.
+    ///
     /// # Examples
     ///
     /// ```no_run