Fix doc nits

Many tiny changes to stdlib doc comments to make them consistent (for example
"Returns foo", rather than "Return foo", per RFC1574), adding missing periods, paragraph
breaks, backticks for monospace style, and other minor nits.

https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text

2 files changed, 34 insertions, 30 deletions

diff --git a/library/core/src/net/ip_addr.rs b/library/core/src/net/ip_addr.rs
index c11a508a135..e9abd57b858 100644
--- a/library/core/src/net/ip_addr.rs
+++ b/library/core/src/net/ip_addr.rs
@@ -406,8 +406,8 @@ impl IpAddr {
         matches!(self, IpAddr::V6(_))
     }
 
-    /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped IPv6 address, otherwise it
-    /// returns `self` as-is.
+    /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped IPv6
+    /// address, otherwise returns `self` as-is.
     ///
     /// # Examples
     ///
@@ -549,7 +549,7 @@ impl Ipv4Addr {
     #[stable(feature = "ip_constructors", since = "1.30.0")]
     pub const UNSPECIFIED: Self = Ipv4Addr::new(0, 0, 0, 0);
 
-    /// An IPv4 address representing the broadcast address: `255.255.255.255`
+    /// An IPv4 address representing the broadcast address: `255.255.255.255`.
     ///
     /// # Examples
     ///
@@ -686,10 +686,10 @@ impl Ipv4Addr {
 
     /// Returns [`true`] if the address appears to be globally reachable
     /// as specified by the [IANA IPv4 Special-Purpose Address Registry].
-    /// Whether or not an address is practically reachable will depend on your network configuration.
     ///
-    /// Most IPv4 addresses are globally reachable;
-    /// unless they are specifically defined as *not* globally reachable.
+    /// Whether or not an address is practically reachable will depend on your
+    /// network configuration. Most IPv4 addresses are globally reachable, unless
+    /// they are specifically defined as *not* globally reachable.
     ///
     /// Non-exhaustive list of notable addresses that are not globally reachable:
     ///
@@ -802,8 +802,10 @@ impl Ipv4Addr {
     }
 
     /// Returns [`true`] if this address part of the `198.18.0.0/15` range, which is reserved for
-    /// network devices benchmarking. This range is defined in [IETF RFC 2544] as `192.18.0.0`
-    /// through `198.19.255.255` but [errata 423] corrects it to `198.18.0.0/15`.
+    /// network devices benchmarking.
+    ///
+    /// This range is defined in [IETF RFC 2544] as `192.18.0.0` through
+    /// `198.19.255.255` but [errata 423] corrects it to `198.18.0.0/15`.
     ///
     /// [IETF RFC 2544]: https://tools.ietf.org/html/rfc2544
     /// [errata 423]: https://www.rfc-editor.org/errata/eid423
@@ -827,10 +829,12 @@ impl Ipv4Addr {
         self.octets()[0] == 198 && (self.octets()[1] & 0xfe) == 18
     }
 
-    /// Returns [`true`] if this address is reserved by IANA for future use. [IETF RFC 1112]
-    /// defines the block of reserved addresses as `240.0.0.0/4`. This range normally includes the
-    /// broadcast address `255.255.255.255`, but this implementation explicitly excludes it, since
-    /// it is obviously not reserved for future use.
+    /// Returns [`true`] if this address is reserved by IANA for future use.
+    ///
+    /// [IETF RFC 1112] defines the block of reserved addresses as `240.0.0.0/4`.
+    /// This range normally includes the broadcast address `255.255.255.255`, but
+    /// this implementation explicitly excludes it, since it is obviously not
+    /// reserved for future use.
     ///
     /// [IETF RFC 1112]: https://tools.ietf.org/html/rfc1112
     ///
@@ -1328,7 +1332,7 @@ impl Ipv6Addr {
     #[stable(feature = "ip_constructors", since = "1.30.0")]
     pub const LOCALHOST: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
 
-    /// An IPv6 address representing the unspecified address: `::`
+    /// An IPv6 address representing the unspecified address: `::`.
     ///
     /// This corresponds to constant `IN6ADDR_ANY_INIT` or `in6addr_any` in other languages.
     ///
@@ -1424,10 +1428,10 @@ impl Ipv6Addr {
 
     /// Returns [`true`] if the address appears to be globally reachable
     /// as specified by the [IANA IPv6 Special-Purpose Address Registry].
-    /// Whether or not an address is practically reachable will depend on your network configuration.
     ///
-    /// Most IPv6 addresses are globally reachable;
-    /// unless they are specifically defined as *not* globally reachable.
+    /// Whether or not an address is practically reachable will depend on your
+    /// network configuration. Most IPv6 addresses are globally reachable, unless
+    /// they are specifically defined as *not* globally reachable.
     ///
     /// Non-exhaustive list of notable addresses that are not globally reachable:
     /// - The [unspecified address] ([`is_unspecified`](Ipv6Addr::is_unspecified))
@@ -1879,8 +1883,8 @@ impl Ipv6Addr {
         }
     }
 
-    /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped address, otherwise it
-    /// returns self wrapped in an `IpAddr::V6`.
+    /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped address,
+    /// otherwise returns self wrapped in an `IpAddr::V6`.
     ///
     /// # Examples
     ///
@@ -1919,7 +1923,7 @@ impl Ipv6Addr {
     }
 }
 
-/// Write an Ipv6Addr, conforming to the canonical style described by
+/// Writes an Ipv6Addr, conforming to the canonical style described by
 /// [RFC 5952](https://tools.ietf.org/html/rfc5952).
 #[stable(feature = "rust1", since = "1.0.0")]
 impl fmt::Display for Ipv6Addr {
@@ -1962,7 +1966,7 @@ impl fmt::Display for Ipv6Addr {
                     longest
                 };
 
-                /// Write a colon-separated part of the address
+                /// Writes a colon-separated part of the address.
                 #[inline]
                 fn fmt_subslice(f: &mut fmt::Formatter<'_>, chunk: &[u16]) -> fmt::Result {
                     if let Some((first, tail)) = chunk.split_first() {
diff --git a/library/core/src/net/parser.rs b/library/core/src/net/parser.rs
index deea8212448..a8ec71f0dd8 100644
--- a/library/core/src/net/parser.rs
+++ b/library/core/src/net/parser.rs
@@ -68,7 +68,7 @@ impl<'a> Parser<'a> {
         self.state.first().map(|&b| char::from(b))
     }
 
-    /// Read the next character from the input
+    /// Reads the next character from the input
     fn read_char(&mut self) -> Option<char> {
         self.state.split_first().map(|(&b, tail)| {
             self.state = tail;
@@ -77,7 +77,7 @@ impl<'a> Parser<'a> {
     }
 
     #[must_use]
-    /// Read the next character from the input if it matches the target.
+    /// Reads the next character from the input if it matches the target.
     fn read_given_char(&mut self, target: char) -> Option<()> {
         self.read_atomically(|p| {
             p.read_char().and_then(|c| if c == target { Some(()) } else { None })
@@ -165,7 +165,7 @@ impl<'a> Parser<'a> {
         }
     }
 
-    /// Read an IPv4 address.
+    /// Reads an IPv4 address.
     fn read_ipv4_addr(&mut self) -> Option<Ipv4Addr> {
         self.read_atomically(|p| {
             let mut groups = [0; 4];
@@ -182,7 +182,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// Read an IPv6 Address.
+    /// Reads an IPv6 address.
     fn read_ipv6_addr(&mut self) -> Option<Ipv6Addr> {
         /// Read a chunk of an IPv6 address into `groups`. Returns the number
         /// of groups read, along with a bool indicating if an embedded
@@ -249,12 +249,12 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// Read an IP Address, either IPv4 or IPv6.
+    /// Reads an IP address, either IPv4 or IPv6.
     fn read_ip_addr(&mut self) -> Option<IpAddr> {
         self.read_ipv4_addr().map(IpAddr::V4).or_else(move || self.read_ipv6_addr().map(IpAddr::V6))
     }
 
-    /// Read a `:` followed by a port in base 10.
+    /// Reads a `:` followed by a port in base 10.
     fn read_port(&mut self) -> Option<u16> {
         self.read_atomically(|p| {
             p.read_given_char(':')?;
@@ -262,7 +262,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// Read a `%` followed by a scope ID in base 10.
+    /// Reads a `%` followed by a scope ID in base 10.
     fn read_scope_id(&mut self) -> Option<u32> {
         self.read_atomically(|p| {
             p.read_given_char('%')?;
@@ -270,7 +270,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// Read an IPv4 address with a port.
+    /// Reads an IPv4 address with a port.
     fn read_socket_addr_v4(&mut self) -> Option<SocketAddrV4> {
         self.read_atomically(|p| {
             let ip = p.read_ipv4_addr()?;
@@ -279,7 +279,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// Read an IPv6 address with a port.
+    /// Reads an IPv6 address with a port.
     fn read_socket_addr_v6(&mut self) -> Option<SocketAddrV6> {
         self.read_atomically(|p| {
             p.read_given_char('[')?;
@@ -292,7 +292,7 @@ impl<'a> Parser<'a> {
         })
     }
 
-    /// Read an IP address with a port
+    /// Reads an IP address with a port.
     fn read_socket_addr(&mut self) -> Option<SocketAddr> {
         self.read_socket_addr_v4()
             .map(SocketAddr::V4)