diff --git a/src/libstd/net/udp.rs b/src/libstd/net/udp.rs
index 164039b303230..79e5ae79e4c01 100644
--- a/src/libstd/net/udp.rs
+++ b/src/libstd/net/udp.rs
@@ -193,6 +193,19 @@ impl UdpSocket {
     /// assert_eq!(socket.peer_addr().unwrap(),
     ///            SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(192, 168, 0, 1), 41203)));
     /// ```
+    ///
+    /// If the socket isn't connected, it will return a [`NotConnected`] error.
+    ///
+    /// [`NotConnected`]: ../../std/io/enum.ErrorKind.html#variant.NotConnected
+    ///
+    /// ```no_run
+    /// #![feature(udp_peer_addr)]
+    /// use std::net::UdpSocket;
+    ///
+    /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address");
+    /// assert_eq!(socket.peer_addr().unwrap_err().kind(),
+    ///            ::std::io::ErrorKind::NotConnected);
+    /// ```
     #[unstable(feature = "udp_peer_addr", issue = "59127")]
     pub fn peer_addr(&self) -> io::Result<SocketAddr> {
         self.0.peer_addr()