Skip to content

Commit 2c59e03

Browse files
authored
Rollup merge of #40838 - lukaramu:std-net-docs, r=GuillaumeGomez
Improve std::net docs Fixes #29363 Summary: * Added a _lot_ of missing links, both to other types/methods and to IETF RFCs, and changed occurences of just "RFC" to "IETF RFC" * Expanded a bunch of top-level docs, specifically the module docs & the docs for `TcpListener`, `TcpStream`, `UdpSocket`, `IpAddr`, `Ipv4Addr`, `Ipv6Addr`, `SocketAddr`, `SocketAddrV4`, `SocketAddrV6`, * Expanded method docs for `SocketAddrV6`, `AddrParseError`, * Various edits for clarity, consistency, and accuracy See the commit descriptions for more detail. Things not done quite as laid out in the task list in #29363: * `AddrParseError` still doesn't have examples, but I wasn't quite sure how to do them; other `FromStr` error types don't have any, either * I didn't link to an IETF RFC in `IpAddr`, but in `Ipv4Addr` and `Ipv6Addr` and linked tho those from `IpAddr`; this seems more appropriate to me * Similarly, I didn't really exand `SocketAddr`'s docs, but elaborated on `SocketAddrV4` and `SocketAddrV6`'s and linked to them from `SocketAddr` Theres definitely still room for improvement, but this should be a good first effort 😄
2 parents 88badb9 + b8cbc5d commit 2c59e03

File tree

6 files changed

+476
-140
lines changed

6 files changed

+476
-140
lines changed

src/libstd/net/addr.rs

Lines changed: 154 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -20,34 +20,95 @@ use vec;
2020
use iter;
2121
use slice;
2222

23-
/// Representation of a socket address for networking applications.
23+
/// An internet socket address, either IPv4 or IPv6.
2424
///
25-
/// A socket address can either represent the IPv4 or IPv6 protocol and is
26-
/// paired with at least a port number as well. Each protocol may have more
27-
/// specific information about the address available to it as well.
25+
/// Internet socket addresses consist of an [IP address], a 16-bit port number, as well
26+
/// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and
27+
/// [`SocketAddrV6`]'s respective documentation for more details.
28+
///
29+
/// [IP address]: ../../std/net/enum.IpAddr.html
30+
/// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
31+
/// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
32+
///
33+
/// # Examples
34+
///
35+
/// ```
36+
/// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
37+
///
38+
/// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
39+
///
40+
/// assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
41+
/// assert_eq!(socket.port(), 8080);
42+
/// assert_eq!(socket.is_ipv4(), true);
43+
/// ```
2844
#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
2945
#[stable(feature = "rust1", since = "1.0.0")]
3046
pub enum SocketAddr {
31-
/// An IPv4 socket address which is a (ip, port) combination.
47+
/// An IPv4 socket address.
3248
#[stable(feature = "rust1", since = "1.0.0")]
3349
V4(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV4),
3450
/// An IPv6 socket address.
3551
#[stable(feature = "rust1", since = "1.0.0")]
3652
V6(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV6),
3753
}
3854

39-
/// An IPv4 socket address which is a (ip, port) combination.
55+
/// An IPv4 socket address.
56+
///
57+
/// IPv4 socket addresses consist of an [IPv4 address] and a 16-bit port number, as
58+
/// stated in [IETF RFC 793].
59+
///
60+
/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
61+
///
62+
/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
63+
/// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
64+
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
65+
///
66+
/// # Examples
67+
///
68+
/// ```
69+
/// use std::net::{Ipv4Addr, SocketAddrV4};
70+
///
71+
/// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
72+
///
73+
/// assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
74+
/// assert_eq!(socket.ip(), &Ipv4Addr::new(127, 0, 0, 1));
75+
/// assert_eq!(socket.port(), 8080);
76+
/// ```
4077
#[derive(Copy)]
4178
#[stable(feature = "rust1", since = "1.0.0")]
4279
pub struct SocketAddrV4 { inner: c::sockaddr_in }
4380

4481
/// An IPv6 socket address.
82+
///
83+
/// IPv6 socket addresses consist of an [Ipv6 address], a 16-bit port number, as well
84+
/// as fields containing the traffic class, the flow label, and a scope identifier
85+
/// (see [IETF RFC 2553, Section 3.3] for more details).
86+
///
87+
/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
88+
///
89+
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
90+
/// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
91+
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
92+
///
93+
/// # Examples
94+
///
95+
/// ```
96+
/// use std::net::{Ipv6Addr, SocketAddrV6};
97+
///
98+
/// let socket = SocketAddrV6::new(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
99+
///
100+
/// assert_eq!("[2001:db8::1]:8080".parse(), Ok(socket));
101+
/// assert_eq!(socket.ip(), &Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
102+
/// assert_eq!(socket.port(), 8080);
103+
/// ```
45104
#[derive(Copy)]
46105
#[stable(feature = "rust1", since = "1.0.0")]
47106
pub struct SocketAddrV6 { inner: c::sockaddr_in6 }
48107

49108
impl SocketAddr {
50-
/// Creates a new socket address from the (ip, port) pair.
109+
/// Creates a new socket address from an [IP address] and a port number.
110+
///
111+
/// [IP address]: ../../std/net/enum.IpAddr.html
51112
///
52113
/// # Examples
53114
///
@@ -84,7 +145,7 @@ impl SocketAddr {
84145
}
85146
}
86147

87-
/// Change the IP address associated with this socket address.
148+
/// Changes the IP address associated with this socket address.
88149
///
89150
/// # Examples
90151
///
@@ -123,7 +184,7 @@ impl SocketAddr {
123184
}
124185
}
125186

126-
/// Change the port number associated with this socket address.
187+
/// Changes the port number associated with this socket address.
127188
///
128189
/// # Examples
129190
///
@@ -142,8 +203,13 @@ impl SocketAddr {
142203
}
143204
}
144205

145-
/// Returns true if the IP in this `SocketAddr` is a valid IPv4 address,
146-
/// false if it's a valid IPv6 address.
206+
/// Returns [`true`] if the [IP address] in this `SocketAddr` is an
207+
/// [IPv4 address], and [`false`] otherwise.
208+
///
209+
/// [`true`]: ../../std/primitive.bool.html
210+
/// [`false`]: ../../std/primitive.bool.html
211+
/// [IP address]: ../../std/net/enum.IpAddr.html
212+
/// [IPv4 address]: ../../std/net/enum.IpAddr.html#variant.V4
147213
///
148214
/// # Examples
149215
///
@@ -164,8 +230,13 @@ impl SocketAddr {
164230
}
165231
}
166232

167-
/// Returns true if the IP in this `SocketAddr` is a valid IPv6 address,
168-
/// false if it's a valid IPv4 address.
233+
/// Returns [`true`] if the [IP address] in this `SocketAddr` is an
234+
/// [IPv6 address], and [`false`] otherwise.
235+
///
236+
/// [`true`]: ../../std/primitive.bool.html
237+
/// [`false`]: ../../std/primitive.bool.html
238+
/// [IP address]: ../../std/net/enum.IpAddr.html
239+
/// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6
169240
///
170241
/// # Examples
171242
///
@@ -189,7 +260,9 @@ impl SocketAddr {
189260
}
190261

191262
impl SocketAddrV4 {
192-
/// Creates a new socket address from the (ip, port) pair.
263+
/// Creates a new socket address from an [IPv4 address] and a port number.
264+
///
265+
/// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
193266
///
194267
/// # Examples
195268
///
@@ -227,7 +300,7 @@ impl SocketAddrV4 {
227300
}
228301
}
229302

230-
/// Change the IP address associated with this socket address.
303+
/// Changes the IP address associated with this socket address.
231304
///
232305
/// # Examples
233306
///
@@ -258,7 +331,7 @@ impl SocketAddrV4 {
258331
ntoh(self.inner.sin_port)
259332
}
260333

261-
/// Change the port number associated with this socket address.
334+
/// Changes the port number associated with this socket address.
262335
///
263336
/// # Examples
264337
///
@@ -276,8 +349,14 @@ impl SocketAddrV4 {
276349
}
277350

278351
impl SocketAddrV6 {
279-
/// Creates a new socket address from the ip/port/flowinfo/scope_id
280-
/// components.
352+
/// Creates a new socket address from an [IPv6 address], a 16-bit port number,
353+
/// and the `flowinfo` and `scope_id` fields.
354+
///
355+
/// For more information on the meaning and layout of the `flowinfo` and `scope_id`
356+
/// parameters, see [IETF RFC 2553, Section 3.3].
357+
///
358+
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
359+
/// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
281360
///
282361
/// # Examples
283362
///
@@ -318,7 +397,7 @@ impl SocketAddrV6 {
318397
}
319398
}
320399

321-
/// Change the IP address associated with this socket address.
400+
/// Changes the IP address associated with this socket address.
322401
///
323402
/// # Examples
324403
///
@@ -349,7 +428,7 @@ impl SocketAddrV6 {
349428
ntoh(self.inner.sin6_port)
350429
}
351430

352-
/// Change the port number associated with this socket address.
431+
/// Changes the port number associated with this socket address.
353432
///
354433
/// # Examples
355434
///
@@ -365,8 +444,17 @@ impl SocketAddrV6 {
365444
self.inner.sin6_port = hton(new_port);
366445
}
367446

368-
/// Returns the flow information associated with this address,
369-
/// corresponding to the `sin6_flowinfo` field in C.
447+
/// Returns the flow information associated with this address.
448+
///
449+
/// This information corresponds to the `sin6_flowinfo` field in C's `netinet/in.h`,
450+
/// as specified in [IETF RFC 2553, Section 3.3].
451+
/// It combines information about the flow label and the traffic class as specified
452+
/// in [IETF RFC 2460], respectively [Section 6] and [Section 7].
453+
///
454+
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
455+
/// [IETF RFC 2460]: https://tools.ietf.org/html/rfc2460
456+
/// [Section 6]: https://tools.ietf.org/html/rfc2460#section-6
457+
/// [Section 7]: https://tools.ietf.org/html/rfc2460#section-7
370458
///
371459
/// # Examples
372460
///
@@ -381,7 +469,11 @@ impl SocketAddrV6 {
381469
self.inner.sin6_flowinfo
382470
}
383471

384-
/// Change the flow information associated with this socket address.
472+
/// Changes the flow information associated with this socket address.
473+
///
474+
/// See the [`flowinfo`] method's documentation for more details.
475+
///
476+
/// [`flowinfo`]: #method.flowinfo
385477
///
386478
/// # Examples
387479
///
@@ -397,8 +489,12 @@ impl SocketAddrV6 {
397489
self.inner.sin6_flowinfo = new_flowinfo;
398490
}
399491

400-
/// Returns the scope ID associated with this address,
401-
/// corresponding to the `sin6_scope_id` field in C.
492+
/// Returns the scope ID associated with this address.
493+
///
494+
/// This information corresponds to the `sin6_scope_id` field in C's `netinet/in.h`,
495+
/// as specified in [IETF RFC 2553, Section 3.3].
496+
///
497+
/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
402498
///
403499
/// # Examples
404500
///
@@ -415,6 +511,10 @@ impl SocketAddrV6 {
415511

416512
/// Change the scope ID associated with this socket address.
417513
///
514+
/// See the [`scope_id`] method's documentation for more details.
515+
///
516+
/// [`scope_id`]: #method.scope_id
517+
///
418518
/// # Examples
419519
///
420520
/// ```
@@ -559,37 +659,51 @@ impl hash::Hash for SocketAddrV6 {
559659
}
560660

561661
/// A trait for objects which can be converted or resolved to one or more
562-
/// `SocketAddr` values.
662+
/// [`SocketAddr`] values.
563663
///
564664
/// This trait is used for generic address resolution when constructing network
565665
/// objects. By default it is implemented for the following types:
566666
///
567-
/// * `SocketAddr`, `SocketAddrV4`, `SocketAddrV6` - `to_socket_addrs` is
568-
/// identity function.
667+
/// * [`SocketAddr`]: [`to_socket_addrs`] is the identity function.
569668
///
570-
/// * `(IpvNAddr, u16)` - `to_socket_addrs` constructs `SocketAddr` trivially.
669+
/// * [`SocketAddrV4`], [`SocketAddrV6`], `(`[`IpAddr`]`, `[`u16`]`)`,
670+
/// `(`[`Ipv4Addr`]`, `[`u16`]`)`, `(`[`Ipv6Addr`]`, `[`u16`]`)`:
671+
/// [`to_socket_addrs`] constructs a [`SocketAddr`] trivially.
571672
///
572-
/// * `(&str, u16)` - the string should be either a string representation of an
573-
/// IP address expected by `FromStr` implementation for `IpvNAddr` or a host
673+
/// * `(`[`&str`]`, `[`u16`]`)`: the string should be either a string representation
674+
/// of an [`IpAddr`] address as expected by [`FromStr`] implementation or a host
574675
/// name.
575676
///
576-
/// * `&str` - the string should be either a string representation of a
577-
/// `SocketAddr` as expected by its `FromStr` implementation or a string like
578-
/// `<host_name>:<port>` pair where `<port>` is a `u16` value.
677+
/// * [`&str`]: the string should be either a string representation of a
678+
/// [`SocketAddr`] as expected by its [`FromStr`] implementation or a string like
679+
/// `<host_name>:<port>` pair where `<port>` is a [`u16`] value.
579680
///
580-
/// This trait allows constructing network objects like `TcpStream` or
581-
/// `UdpSocket` easily with values of various types for the bind/connection
681+
/// This trait allows constructing network objects like [`TcpStream`] or
682+
/// [`UdpSocket`] easily with values of various types for the bind/connection
582683
/// address. It is needed because sometimes one type is more appropriate than
583684
/// the other: for simple uses a string like `"localhost:12345"` is much nicer
584-
/// than manual construction of the corresponding `SocketAddr`, but sometimes
585-
/// `SocketAddr` value is *the* main source of the address, and converting it to
685+
/// than manual construction of the corresponding [`SocketAddr`], but sometimes
686+
/// [`SocketAddr`] value is *the* main source of the address, and converting it to
586687
/// some other type (e.g. a string) just for it to be converted back to
587-
/// `SocketAddr` in constructor methods is pointless.
688+
/// [`SocketAddr`] in constructor methods is pointless.
588689
///
589690
/// Addresses returned by the operating system that are not IP addresses are
590691
/// silently ignored.
591692
///
592-
/// Some examples:
693+
/// [`FromStr`]: ../../std/str/trait.FromStr.html
694+
/// [`IpAddr`]: ../../std/net/enum.IpAddr.html
695+
/// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
696+
/// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
697+
/// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
698+
/// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
699+
/// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
700+
/// [`&str`]: ../../std/primitive.str.html
701+
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
702+
/// [`to_socket_addrs`]: #tymethod.to_socket_addrs
703+
/// [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
704+
/// [`u16`]: ../../std/primitive.u16.html
705+
///
706+
/// # Examples
593707
///
594708
/// ```no_run
595709
/// use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};
@@ -629,10 +743,6 @@ pub trait ToSocketAddrs {
629743
///
630744
/// Note that this function may block the current thread while resolution is
631745
/// performed.
632-
///
633-
/// # Errors
634-
///
635-
/// Any errors encountered during resolution will be returned as an `Err`.
636746
#[stable(feature = "rust1", since = "1.0.0")]
637747
fn to_socket_addrs(&self) -> io::Result<Self::Iter>;
638748
}

0 commit comments

Comments
 (0)