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.)

1 files changed, 39 insertions, 0 deletions

diff --git a/library/core/src/net/socket_addr.rs b/library/core/src/net/socket_addr.rs
index 4e339172b68..a46495add6a 100644
--- a/library/core/src/net/socket_addr.rs
+++ b/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")]