Rollup merge of #131790 - nmathewson:doc_socketaddr_representation, r…

…=tgross35

Document textual format of SocketAddrV{4,6}

This commit adds new "Textual representation" documentation sections to SocketAddrV4 and SocketAddrV6, by analogy to the existing "textual representation" sections of Ipv4Addr and Ipv6Addr.

Rationale: Without documentation about which formats are actually accepted, it's hard for a programmer to be sure that their code will actually behave as expected when implementing protocols that require support (or rejection) for particular representations. This lack of clarity can in turn can lead to ambiguities and security problems like those discussed in RFC 6942.

(I've tried to describe the governing RFCs or standards where I could, but it's possible that the actual implementers had something else in mind.  I could not find any standards that corresponded _exactly_ to the one implemented in SocketAddrv6, but I have linked the relevant documents that I could find.)

library/core/src/net/socket_addr.rs

@@ -49,6 +49,15 @@ pub enum SocketAddr {
 /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
 /// [`IPv4` address]: Ipv4Addr
 ///
+/// # Textual representation
+///
+/// `SocketAddrV4` provides a [`FromStr`](crate::str::FromStr) implementation.
+/// It accepts an IPv4 address in its [textual representation], followed by a
+/// single `:`, followed by the port encoded as a decimal integer.  Other
+/// formats are not accepted.
+///
+/// [textual representation]: Ipv4Addr#textual-representation
+///
 /// # Examples
 ///
 /// ```
@@ -82,6 +91,32 @@ pub struct SocketAddrV4 {
 /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
 /// [`IPv6` address]: Ipv6Addr
 ///
+/// # Textual representation
+///
+/// `SocketAddrV6` provides a [`FromStr`](crate::str::FromStr) implementation,
+/// based on the bracketed format recommended by [IETF RFC 5952],
+/// with scope identifiers based on those specified in [IETF RFC 4007].
+///
+/// It accepts addresses consisting of the following elements, in order:
+///   - A left square bracket (`[`)
+///   - The [textual representation] of an IPv6 address
+///   - _Optionally_, a percent sign (`%`) followed by the scope identifier
+///     encoded as a decimal integer
+///   - A right square bracket (`]`)
+///   - A colon (`:`)
+///   - The port, encoded as a decimal integer.
+///
+/// For example, the string `[2001:db8::413]:443` represents a `SocketAddrV6`
+/// with the address `2001:db8::413` and port `443`.  The string
+/// `[2001:db8::413%612]:443` represents the same address and port, with a
+/// scope identifier of `612`.
+///
+/// Other formats are not accepted.
+///
+/// [IETF RFC 5952]: https://tools.ietf.org/html/rfc5952#section-6
+/// [IETF RFC 4007]: https://tools.ietf.org/html/rfc4007#section-11
+/// [textual representation]: Ipv6Addr#textual-representation
+///
 /// # Examples
 ///
 /// ```
@@ -92,6 +127,10 @@ pub struct SocketAddrV4 {
 /// assert_eq!("[2001:db8::1]:8080".parse(), Ok(socket));
 /// assert_eq!(socket.ip(), &Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
 /// assert_eq!(socket.port(), 8080);
+///
+/// let mut with_scope = socket.clone();
+/// with_scope.set_scope_id(3);
+/// assert_eq!("[2001:db8::1%3]:8080".parse(), Ok(with_scope));
 /// ```
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
 #[stable(feature = "rust1", since = "1.0.0")]