Addressed requested changes for PR #40838

* Fixed spelling ToSocketAddr -> ToSocketAddrs in module docs
  (which also fixes a link)
* Added missing "when" before "interacting" in module docs
* Changed SocketAddr's top-level docs to explicitly state what socket
  addresses consist of, making them more consistent with SocketAddrV4's
  and SocketAddrV6's docs
* Changed "in C" -> "in C's `netinet/in.h`"
* Changed wording in is_ipv4/is_ipv6 methods to ", `false` otherwise"
* Add missing closing ` ``` ` in Ipv6Addr's examples
* Removed "Errors" section in ToSocketAddrs' to_socket_addrs method as it
  was rather redundant

3 files changed, 17 insertions, 26 deletions

diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs
index ccfd2a1dfb1..36c06dc0b58 100644
--- a/src/libstd/net/addr.rs
+++ b/src/libstd/net/addr.rs
@@ -22,9 +22,11 @@ use slice;
 
 /// An internet socket address, either IPv4 or IPv6.
 ///
-/// This enum can contain either an [`SocketAddrV4`] or an [`SocketAddrV6`]. see their
-/// respective documentation for more details.
+/// Internet socket addresses consist of an [IP address], a 16-bit port number, as well
+/// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and
+/// [`SocketAddrV6`]'s respective documentation for more details.
 ///
+/// [IP address]: ../../std/net/enum.IpAddr.html
 /// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
 /// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
 ///
@@ -202,13 +204,12 @@ impl SocketAddr {
     }
 
     /// Returns [`true`] if the [IP address] in this `SocketAddr` is an
-    /// [IPv4 address] and [`false`] if it's an [IPv6 address].
+    /// [IPv4 address], and [`false`] otherwise.
     ///
     /// [`true`]: ../../std/primitive.bool.html
     /// [`false`]: ../../std/primitive.bool.html
     /// [IP address]: ../../std/net/enum.IpAddr.html
     /// [IPv4 address]: ../../std/net/enum.IpAddr.html#variant.V4
-    /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6
     ///
     /// # Examples
     ///
@@ -230,12 +231,11 @@ impl SocketAddr {
     }
 
     /// Returns [`true`] if the [IP address] in this `SocketAddr` is an
-    /// [IPv6 address] and [`false`] if it's an [IPv4 address].
+    /// [IPv6 address], and [`false`] otherwise.
     ///
     /// [`true`]: ../../std/primitive.bool.html
     /// [`false`]: ../../std/primitive.bool.html
     /// [IP address]: ../../std/net/enum.IpAddr.html
-    /// [IPv4 address]: ../../std/net/enum.IpAddr.html#variant.V4
     /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6
     ///
     /// # Examples
@@ -446,10 +446,10 @@ impl SocketAddrV6 {
 
     /// Returns the flow information associated with this address.
     ///
-    /// This information corresponds to the `sin6_flowinfo` field in C, as specified in
-    /// [IETF RFC 2553, Section 3.3]. It combines information about the flow label and
-    /// the traffic class as specified in [IETF RFC 2460], respectively [Section 6] and
-    /// [Section 7].
+    /// This information corresponds to the `sin6_flowinfo` field in C's `netinet/in.h`,
+    /// as specified in [IETF RFC 2553, Section 3.3].
+    /// It combines information about the flow label and the traffic class as specified
+    /// in [IETF RFC 2460], respectively [Section 6] and [Section 7].
     ///
     /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
     /// [IETF RFC 2460]: https://tools.ietf.org/html/rfc2460
@@ -491,8 +491,8 @@ impl SocketAddrV6 {
 
     /// Returns the scope ID associated with this address.
     ///
-    /// This information corresponds to the `sin6_scope_id` field in C, as specified in
-    /// [IETF RFC 2553, Section 3.3].
+    /// This information corresponds to the `sin6_scope_id` field in C's `netinet/in.h`,
+    /// as specified in [IETF RFC 2553, Section 3.3].
     ///
     /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
     ///
@@ -743,12 +743,6 @@ pub trait ToSocketAddrs {
     ///
     /// Note that this function may block the current thread while resolution is
     /// performed.
-    ///
-    /// # Errors
-    ///
-    /// Any errors encountered during resolution will be returned as an [`Err`].
-    ///
-    /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
     #[stable(feature = "rust1", since = "1.0.0")]
     fn to_socket_addrs(&self) -> io::Result<Self::Iter>;
 }
diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs
index 2a1f959b35d..c46fe4a58c7 100644
--- a/src/libstd/net/ip.rs
+++ b/src/libstd/net/ip.rs
@@ -114,6 +114,7 @@ pub struct Ipv4Addr {
 /// let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
 /// assert_eq!("::1".parse(), Ok(localhost));
 /// assert_eq!(localhost.is_loopback(), true);
+/// ```
 #[derive(Copy)]
 #[stable(feature = "rust1", since = "1.0.0")]
 pub struct Ipv6Addr {
@@ -266,13 +267,11 @@ impl IpAddr {
         }
     }
 
-    /// Returns [`true`] if this address is an [IPv4 address] and [`false`] if it's an
-    /// [IPv6 address].
+    /// Returns [`true`] if this address is an [IPv4 address], and [`false`] otherwise.
     ///
     /// [`true`]: ../../std/primitive.bool.html
     /// [`false`]: ../../std/primitive.bool.html
     /// [IPv4 address]: #variant.V4
-    /// [IPv6 address]: #variant.V6
     ///
     /// # Examples
     ///
@@ -293,12 +292,10 @@ impl IpAddr {
         }
     }
 
-    /// Returns [`true`] if this address is an [IPv6 address] and [`false`] if it's an
-    /// [IPv4 address].
+    /// Returns [`true`] if this address is an [IPv6 address], and [`false`] otherwise.
     ///
     /// [`true`]: ../../std/primitive.bool.html
     /// [`false`]: ../../std/primitive.bool.html
-    /// [IPv4 address]: #variant.V4
     /// [IPv6 address]: #variant.V6
     ///
     /// # Examples
diff --git a/src/libstd/net/mod.rs b/src/libstd/net/mod.rs
index 3b4808fee25..9fcb93e2032 100644
--- a/src/libstd/net/mod.rs
+++ b/src/libstd/net/mod.rs
@@ -21,7 +21,7 @@
 //!   [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses
 //! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`]
 //!   and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses
-//! * [`ToSocketAddr`] is a trait that used for generic address resolution interacting
+//! * [`ToSocketAddrs`] is a trait that used for generic address resolution when interacting
 //!   with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`]
 //! * Other types are return or parameter types for various methods in this module
 //!
@@ -33,7 +33,7 @@
 //! [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
 //! [`TcpListener`]: ../../std/net/struct.TcpListener.html
 //! [`TcpStream`]: ../../std/net/struct.TcpStream.html
-//! [`ToSocketAddr`]: ../../std/net/trait.ToSocketAddr.html
+//! [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
 //! [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
 
 #![stable(feature = "rust1", since = "1.0.0")]