From 27acb5ca11cea8c48030f440772111805dbb9520 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 16 Nov 2016 19:56:01 +0100 Subject: [PATCH 1/2] Add missing urls and improve internal doc representation --- src/libstd/net/ip.rs | 24 +++++++++++++++++++----- src/libstd/net/tcp.rs | 3 ++- 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 49080680fac63..e85c95198c74b 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -176,8 +176,9 @@ impl Ipv4Addr { /// Returns true for the special 'unspecified' address (0.0.0.0). /// /// This property is defined in _UNIX Network Programming, Second Edition_, - /// W. Richard Stevens, p. 891; see also [ip7] - /// [ip7][http://man7.org/linux/man-pages/man7/ip.7.html] + /// W. Richard Stevens, p. 891; see also [ip7]. + /// + /// [ip7]: (http://man7.org/linux/man-pages/man7/ip.7.html) #[stable(feature = "ip_shared", since = "1.12.0")] pub fn is_unspecified(&self) -> bool { self.inner.s_addr == 0 @@ -186,6 +187,7 @@ impl Ipv4Addr { /// Returns true if this is a loopback address (127.0.0.0/8). /// /// This property is defined by [RFC 1122]. + /// /// [RFC 1122]: https://tools.ietf.org/html/rfc1122 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_loopback(&self) -> bool { @@ -195,11 +197,12 @@ impl Ipv4Addr { /// Returns true if this is a private address. /// /// The private address ranges are defined in [RFC 1918] and include: - /// [RFC 1918]: https://tools.ietf.org/html/rfc1918 /// /// - 10.0.0.0/8 /// - 172.16.0.0/12 /// - 192.168.0.0/16 + /// + /// [RFC 1918]: https://tools.ietf.org/html/rfc1918 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_private(&self) -> bool { match (self.octets()[0], self.octets()[1]) { @@ -213,6 +216,7 @@ impl Ipv4Addr { /// Returns true if the address is link-local (169.254.0.0/16). /// /// This property is defined by [RFC 3927]. + /// /// [RFC 3927]: https://tools.ietf.org/html/rfc3927 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_link_local(&self) -> bool { @@ -221,7 +225,6 @@ impl Ipv4Addr { /// Returns true if the address appears to be globally routable. /// See [iana-ipv4-special-registry][ipv4-sr]. - /// [ipv4-sr]: http://goo.gl/RaZ7lg /// /// The following return false: /// @@ -231,6 +234,8 @@ impl Ipv4Addr { /// - the broadcast address (255.255.255.255/32) /// - test addresses used for documentation (192.0.2.0/24, 198.51.100.0/24 and 203.0.113.0/24) /// - the unspecified address (0.0.0.0) + /// + /// [ipv4-sr]: http://goo.gl/RaZ7lg pub fn is_global(&self) -> bool { !self.is_private() && !self.is_loopback() && !self.is_link_local() && !self.is_broadcast() && !self.is_documentation() && !self.is_unspecified() @@ -240,6 +245,7 @@ impl Ipv4Addr { /// /// Multicast addresses have a most significant octet between 224 and 239, /// and is defined by [RFC 5771]. + /// /// [RFC 5771]: https://tools.ietf.org/html/rfc5771 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_multicast(&self) -> bool { @@ -249,6 +255,7 @@ impl Ipv4Addr { /// Returns true if this is a broadcast address (255.255.255.255). /// /// A broadcast address has all octets set to 255 as defined in [RFC 919]. + /// /// [RFC 919]: https://tools.ietf.org/html/rfc919 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_broadcast(&self) -> bool { @@ -259,11 +266,12 @@ impl Ipv4Addr { /// Returns true if this address is in a range designated for documentation. /// /// This is defined in [RFC 5737]: - /// [RFC 5737]: https://tools.ietf.org/html/rfc5737 /// /// - 192.0.2.0/24 (TEST-NET-1) /// - 198.51.100.0/24 (TEST-NET-2) /// - 203.0.113.0/24 (TEST-NET-3) + /// + /// [RFC 5737]: https://tools.ietf.org/html/rfc5737 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_documentation(&self) -> bool { match(self.octets()[0], self.octets()[1], self.octets()[2], self.octets()[3]) { @@ -425,6 +433,7 @@ impl Ipv6Addr { /// Returns true for the special 'unspecified' address (::). /// /// This property is defined in [RFC 4291]. + /// /// [RFC 4291]: https://tools.ietf.org/html/rfc4291 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_unspecified(&self) -> bool { @@ -434,6 +443,7 @@ impl Ipv6Addr { /// Returns true if this is a loopback address (::1). /// /// This property is defined in [RFC 4291]. + /// /// [RFC 4291]: https://tools.ietf.org/html/rfc4291 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_loopback(&self) -> bool { @@ -458,6 +468,7 @@ impl Ipv6Addr { /// Returns true if this is a unique local address (fc00::/7). /// /// This property is defined in [RFC 4193]. + /// /// [RFC 4193]: https://tools.ietf.org/html/rfc4193 pub fn is_unique_local(&self) -> bool { (self.segments()[0] & 0xfe00) == 0xfc00 @@ -466,6 +477,7 @@ impl Ipv6Addr { /// Returns true if the address is unicast and link-local (fe80::/10). /// /// This property is defined in [RFC 4291]. + /// /// [RFC 4291]: https://tools.ietf.org/html/rfc4291 pub fn is_unicast_link_local(&self) -> bool { (self.segments()[0] & 0xffc0) == 0xfe80 @@ -481,6 +493,7 @@ impl Ipv6Addr { /// (2001:db8::/32). /// /// This property is defined in [RFC 3849]. + /// /// [RFC 3849]: https://tools.ietf.org/html/rfc3849 pub fn is_documentation(&self) -> bool { (self.segments()[0] == 0x2001) && (self.segments()[1] == 0xdb8) @@ -524,6 +537,7 @@ impl Ipv6Addr { /// Returns true if this is a multicast address (ff00::/8). /// /// This property is defined by [RFC 4291]. + /// /// [RFC 4291]: https://tools.ietf.org/html/rfc4291 #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_multicast(&self) -> bool { diff --git a/src/libstd/net/tcp.rs b/src/libstd/net/tcp.rs index 0e7c5b06713fb..159aa997b2728 100644 --- a/src/libstd/net/tcp.rs +++ b/src/libstd/net/tcp.rs @@ -67,11 +67,12 @@ pub struct TcpListener(net_imp::TcpListener); /// An infinite iterator over the connections from a `TcpListener`. /// -/// This iterator will infinitely yield `Some` of the accepted connections. It +/// This iterator will infinitely yield [`Some`] of the accepted connections. It /// is equivalent to calling `accept` in a loop. /// /// This `struct` is created by the [`incoming`] method on [`TcpListener`]. /// +/// [`Some`]: ../../std/option/enum.Option.html#variant.Some /// [`incoming`]: struct.TcpListener.html#method.incoming /// [`TcpListener`]: struct.TcpListener.html #[stable(feature = "rust1", since = "1.0.0")] From 976bfc032266e1b6f8281c1f08df3d6cb8242776 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 16 Nov 2016 20:40:01 +0100 Subject: [PATCH 2/2] Add examples for Ipv4Addr --- src/libstd/net/ip.rs | 125 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 124 insertions(+), 1 deletion(-) diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index e85c95198c74b..7b7be6e2eeeb3 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -154,6 +154,14 @@ impl Ipv4Addr { /// Creates a new IPv4 address from four eight-bit octets. /// /// The result will represent the IP address `a`.`b`.`c`.`d`. + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// let addr = Ipv4Addr::new(127, 0, 0, 1); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr { Ipv4Addr { @@ -167,6 +175,15 @@ impl Ipv4Addr { } /// Returns the four eight-bit integers that make up this address. + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// let addr = Ipv4Addr::new(127, 0, 0, 1); + /// assert_eq!(addr.octets(), [127, 0, 0, 1]); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn octets(&self) -> [u8; 4] { let bits = ntoh(self.inner.s_addr); @@ -178,7 +195,16 @@ impl Ipv4Addr { /// This property is defined in _UNIX Network Programming, Second Edition_, /// W. Richard Stevens, p. 891; see also [ip7]. /// - /// [ip7]: (http://man7.org/linux/man-pages/man7/ip.7.html) + /// [ip7]: http://man7.org/linux/man-pages/man7/ip.7.html + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_unspecified(), true); + /// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_unspecified(), false); + /// ``` #[stable(feature = "ip_shared", since = "1.12.0")] pub fn is_unspecified(&self) -> bool { self.inner.s_addr == 0 @@ -189,6 +215,15 @@ impl Ipv4Addr { /// This property is defined by [RFC 1122]. /// /// [RFC 1122]: https://tools.ietf.org/html/rfc1122 + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(127, 0, 0, 1).is_loopback(), true); + /// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_loopback(), false); + /// ``` #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_loopback(&self) -> bool { self.octets()[0] == 127 @@ -203,6 +238,20 @@ impl Ipv4Addr { /// - 192.168.0.0/16 /// /// [RFC 1918]: https://tools.ietf.org/html/rfc1918 + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(10, 0, 0, 1).is_private(), true); + /// assert_eq!(Ipv4Addr::new(10, 10, 10, 10).is_private(), true); + /// assert_eq!(Ipv4Addr::new(172, 16, 10, 10).is_private(), true); + /// assert_eq!(Ipv4Addr::new(172, 29, 45, 14).is_private(), true); + /// assert_eq!(Ipv4Addr::new(172, 32, 0, 2).is_private(), false); + /// assert_eq!(Ipv4Addr::new(192, 168, 0, 2).is_private(), true); + /// assert_eq!(Ipv4Addr::new(192, 169, 0, 2).is_private(), false); + /// ``` #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_private(&self) -> bool { match (self.octets()[0], self.octets()[1]) { @@ -218,6 +267,16 @@ impl Ipv4Addr { /// This property is defined by [RFC 3927]. /// /// [RFC 3927]: https://tools.ietf.org/html/rfc3927 + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(169, 254, 0, 0).is_link_local(), true); + /// assert_eq!(Ipv4Addr::new(169, 254, 10, 65).is_link_local(), true); + /// assert_eq!(Ipv4Addr::new(16, 89, 10, 65).is_link_local(), false); + /// ``` #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_link_local(&self) -> bool { self.octets()[0] == 169 && self.octets()[1] == 254 @@ -236,6 +295,22 @@ impl Ipv4Addr { /// - the unspecified address (0.0.0.0) /// /// [ipv4-sr]: http://goo.gl/RaZ7lg + /// + /// # Examples + /// + /// ``` + /// #![feature(ip)] + /// + /// use std::net::Ipv4Addr; + /// + /// fn main() { + /// assert_eq!(Ipv4Addr::new(10, 254, 0, 0).is_global(), false); + /// assert_eq!(Ipv4Addr::new(192, 168, 10, 65).is_global(), false); + /// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_global(), false); + /// assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_global(), false); + /// assert_eq!(Ipv4Addr::new(80, 9, 12, 3).is_global(), true); + /// } + /// ``` pub fn is_global(&self) -> bool { !self.is_private() && !self.is_loopback() && !self.is_link_local() && !self.is_broadcast() && !self.is_documentation() && !self.is_unspecified() @@ -247,6 +322,16 @@ impl Ipv4Addr { /// and is defined by [RFC 5771]. /// /// [RFC 5771]: https://tools.ietf.org/html/rfc5771 + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(224, 254, 0, 0).is_multicast(), true); + /// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_multicast(), true); + /// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_multicast(), false); + /// ``` #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_multicast(&self) -> bool { self.octets()[0] >= 224 && self.octets()[0] <= 239 @@ -257,6 +342,15 @@ impl Ipv4Addr { /// A broadcast address has all octets set to 255 as defined in [RFC 919]. /// /// [RFC 919]: https://tools.ietf.org/html/rfc919 + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_broadcast(), true); + /// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_broadcast(), false); + /// ``` #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_broadcast(&self) -> bool { self.octets()[0] == 255 && self.octets()[1] == 255 && @@ -272,6 +366,17 @@ impl Ipv4Addr { /// - 203.0.113.0/24 (TEST-NET-3) /// /// [RFC 5737]: https://tools.ietf.org/html/rfc5737 + /// + /// # Examples + /// + /// ``` + /// use std::net::Ipv4Addr; + /// + /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_documentation(), true); + /// assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_documentation(), true); + /// assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_documentation(), true); + /// assert_eq!(Ipv4Addr::new(193, 34, 17, 19).is_documentation(), false); + /// ``` #[stable(since = "1.7.0", feature = "ip_17")] pub fn is_documentation(&self) -> bool { match(self.octets()[0], self.octets()[1], self.octets()[2], self.octets()[3]) { @@ -285,6 +390,15 @@ impl Ipv4Addr { /// Converts this address to an IPv4-compatible IPv6 address. /// /// a.b.c.d becomes ::a.b.c.d + /// + /// # Examples + /// + /// ``` + /// use std::net::{Ipv4Addr, Ipv6Addr}; + /// + /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_compatible(), + /// Ipv6Addr::new(0, 0, 0, 0, 0, 0, 49152, 767)); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn to_ipv6_compatible(&self) -> Ipv6Addr { Ipv6Addr::new(0, 0, 0, 0, 0, 0, @@ -295,6 +409,15 @@ impl Ipv4Addr { /// Converts this address to an IPv4-mapped IPv6 address. /// /// a.b.c.d becomes ::ffff:a.b.c.d + /// + /// # Examples + /// + /// ``` + /// use std::net::{Ipv4Addr, Ipv6Addr}; + /// + /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped(), + /// Ipv6Addr::new(0, 0, 0, 0, 0, 65535, 49152, 767)); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn to_ipv6_mapped(&self) -> Ipv6Addr { Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff,