Document transient connection errors from TcpListener::accept

library/std/src/net/tcp.rs

@@ -876,6 +876,22 @@ impl TcpListener {
     /// is established. When established, the corresponding [`TcpStream`] and the
     /// remote peer's address will be returned.
     ///
+    /// # Errors
+    ///
+    /// Some errors returned by this function relate to a single incoming
+    /// connection that failed before it could be accepted, such as one aborted
+    /// by the peer ([`ConnectionAborted`]). Such an error does not indicate a
+    /// problem with the listener itself, which remains usable. Code serving a
+    /// long-lived listener will usually want to log the error and continue
+    /// accepting connections rather than treat it as fatal. Which errors can
+    /// occur this way is platform-specific.
+    ///
+    /// On Unix, [`Interrupted`] errors are retried internally rather than being
+    /// returned.
+    ///
+    /// [`ConnectionAborted`]: io::ErrorKind::ConnectionAborted
+    /// [`Interrupted`]: io::ErrorKind::Interrupted
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -902,6 +918,11 @@ impl TcpListener {
     /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to
     /// calling [`TcpListener::accept`] in a loop.
     ///
+    /// # Errors
+    ///
+    /// Each connection yielded by the iterator can fail for the same reasons as
+    /// [`TcpListener::accept`]; see its documentation for details.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -937,6 +958,11 @@ impl TcpListener {
     /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to
     /// calling [`TcpListener::accept`] in a loop.
     ///
+    /// # Errors
+    ///
+    /// Each connection yielded by the iterator can fail for the same reasons as
+    /// [`TcpListener::accept`]; see its documentation for details.
+    ///
     /// # Examples
     ///
     /// ```no_run