From 5e991e1b7ee3ddbd160203dec84bef10b45c1589 Mon Sep 17 00:00:00 2001 From: Anthony Defranceschi Date: Thu, 8 Mar 2018 23:18:45 +0100 Subject: [PATCH] Improve `AddrParseError` documentation. Add a potential cause to `AddrParseError` raising. --- src/libstd/net/parser.rs | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/libstd/net/parser.rs b/src/libstd/net/parser.rs index 261d44eebaa27..ae5037cc44e80 100644 --- a/src/libstd/net/parser.rs +++ b/src/libstd/net/parser.rs @@ -372,6 +372,25 @@ impl FromStr for SocketAddr { /// [`IpAddr`], [`Ipv4Addr`], [`Ipv6Addr`], [`SocketAddr`], [`SocketAddrV4`], and /// [`SocketAddrV6`]. /// +/// # Potential causes +/// +/// `AddrParseError` may be thrown because the provided string does not parse as the given type, +/// often because it includes information only handled by a different address type. +/// +/// ```should_panic +/// use std::net::IpAddr; +/// let _foo: IpAddr = "127.0.0.1:8080".parse().expect("Cannot handle the socket port"); +/// ``` +/// +/// [`IpAddr`] doesn't handle the port. Use [`SocketAddr`] instead. +/// +/// ``` +/// use std::net::SocketAddr; +/// +/// // No problem, the `panic!` message has disappeared. +/// let _foo: SocketAddr = "127.0.0.1:8080".parse().expect("unreachable panic"); +/// ``` +/// /// [`FromStr`]: ../../std/str/trait.FromStr.html /// [`IpAddr`]: ../../std/net/enum.IpAddr.html /// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html