From 908328fca03c1bf69ce335974f4dcabd8e5d18f4 Mon Sep 17 00:00:00 2001 From: Phlosioneer Date: Sun, 11 Mar 2018 07:41:13 -0400 Subject: [PATCH 1/4] Document when types have OS-dependent sizes As per issue #43601, types that can change size depending on the target operating system should say so in their documentation. I used this template when adding doc comments: The size of a(n) struct may vary depending on the target operating system, and may change between Rust releases. For enums, I used "instance" instead of "struct". --- src/libstd/io/stdio.rs | 9 +++++++++ src/libstd/net/addr.rs | 9 +++++++++ src/libstd/net/ip.rs | 9 +++++++++ src/libstd/time.rs | 6 ++++++ 4 files changed, 33 insertions(+) diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index 1f73054e3be..4565b7fa0d6 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -30,18 +30,27 @@ thread_local! { /// /// This handle is not synchronized or buffered in any fashion. Constructed via /// the `std::io::stdio::stdin_raw` function. +/// +/// The size of a StdinRaw struct may vary depending on the target operating +/// system, and may change between Rust releases. struct StdinRaw(stdio::Stdin); /// A handle to a raw instance of the standard output stream of this process. /// /// This handle is not synchronized or buffered in any fashion. Constructed via /// the `std::io::stdio::stdout_raw` function. +/// +/// The size of a StdoutRaw struct may vary depending on the target operating +/// system, and may change between Rust releases. struct StdoutRaw(stdio::Stdout); /// A handle to a raw instance of the standard output stream of this process. /// /// This handle is not synchronized or buffered in any fashion. Constructed via /// the `std::io::stdio::stderr_raw` function. +/// +/// The size of a StderrRaw struct may vary depending on the target operating +/// system, and may change between Rust releases. struct StderrRaw(stdio::Stderr); /// Constructs a new raw handle to the standard input of this process. diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index fa430939f05..75b05063839 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -28,6 +28,9 @@ use slice; /// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and /// [`SocketAddrV6`]'s respective documentation for more details. /// +/// The size of a SocketAddr instance may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [IP address]: ../../std/net/enum.IpAddr.html /// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html /// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html @@ -61,6 +64,9 @@ pub enum SocketAddr { /// /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. /// +/// The size of a SocketAddrV4 struct may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 /// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html @@ -88,6 +94,9 @@ pub struct SocketAddrV4 { inner: c::sockaddr_in } /// /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. /// +/// The size of a SocketAddrV6 struct may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 /// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 0d73a6f4fd7..36a34e147d5 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -26,6 +26,9 @@ use sys_common::{AsInner, FromInner}; /// This enum can contain either an [`Ipv4Addr`] or an [`Ipv6Addr`], see their /// respective documentation for more details. /// +/// The size of an IpAddr instance may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html /// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html /// @@ -61,6 +64,9 @@ pub enum IpAddr { /// /// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. /// +/// The size of an Ipv4Addr struct may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [IETF RFC 791]: https://tools.ietf.org/html/rfc791 /// [`IpAddr`]: ../../std/net/enum.IpAddr.html /// @@ -93,6 +99,9 @@ pub struct Ipv4Addr { /// /// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. /// +/// The size of an Ipv6Addr struct may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 /// [`IpAddr`]: ../../std/net/enum.IpAddr.html /// diff --git a/src/libstd/time.rs b/src/libstd/time.rs index 12f2a9bb85f..054450a5186 100644 --- a/src/libstd/time.rs +++ b/src/libstd/time.rs @@ -49,6 +49,9 @@ pub use core::time::Duration; /// allows measuring the duration between two instants (or comparing two /// instants). /// +/// The size of an Instant struct may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// Example: /// /// ```no_run @@ -88,6 +91,9 @@ pub struct Instant(time::Instant); /// fixed point in time, a `SystemTime` can be converted to a human-readable time, /// or perhaps some other string representation. /// +/// The size of a SystemTime struct may vary depending on the target operating +/// system, and may change between Rust releases. +/// /// [`Instant`]: ../../std/time/struct.Instant.html /// [`Result`]: ../../std/result/enum.Result.html /// [`Duration`]: ../../std/time/struct.Duration.html From e63b1a0e368e2f7d3bf5eadd1262dc530a38394b Mon Sep 17 00:00:00 2001 From: Phlosioneer Date: Sun, 11 Mar 2018 17:17:18 -0400 Subject: [PATCH 2/4] Remove "and may change between Rust releases" --- src/libstd/io/stdio.rs | 6 +++--- src/libstd/net/addr.rs | 6 +++--- src/libstd/net/ip.rs | 6 +++--- src/libstd/time.rs | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index 4565b7fa0d6..9a4cde7e162 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -32,7 +32,7 @@ thread_local! { /// the `std::io::stdio::stdin_raw` function. /// /// The size of a StdinRaw struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. struct StdinRaw(stdio::Stdin); /// A handle to a raw instance of the standard output stream of this process. @@ -41,7 +41,7 @@ struct StdinRaw(stdio::Stdin); /// the `std::io::stdio::stdout_raw` function. /// /// The size of a StdoutRaw struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. struct StdoutRaw(stdio::Stdout); /// A handle to a raw instance of the standard output stream of this process. @@ -50,7 +50,7 @@ struct StdoutRaw(stdio::Stdout); /// the `std::io::stdio::stderr_raw` function. /// /// The size of a StderrRaw struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. struct StderrRaw(stdio::Stderr); /// Constructs a new raw handle to the standard input of this process. diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 75b05063839..f985c1f2bc8 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -29,7 +29,7 @@ use slice; /// [`SocketAddrV6`]'s respective documentation for more details. /// /// The size of a SocketAddr instance may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [IP address]: ../../std/net/enum.IpAddr.html /// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html @@ -65,7 +65,7 @@ pub enum SocketAddr { /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. /// /// The size of a SocketAddrV4 struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 /// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html @@ -95,7 +95,7 @@ pub struct SocketAddrV4 { inner: c::sockaddr_in } /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. /// /// The size of a SocketAddrV6 struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 /// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 36a34e147d5..67b9e7a2f9d 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -27,7 +27,7 @@ use sys_common::{AsInner, FromInner}; /// respective documentation for more details. /// /// The size of an IpAddr instance may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html /// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html @@ -65,7 +65,7 @@ pub enum IpAddr { /// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. /// /// The size of an Ipv4Addr struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [IETF RFC 791]: https://tools.ietf.org/html/rfc791 /// [`IpAddr`]: ../../std/net/enum.IpAddr.html @@ -100,7 +100,7 @@ pub struct Ipv4Addr { /// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. /// /// The size of an Ipv6Addr struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 /// [`IpAddr`]: ../../std/net/enum.IpAddr.html diff --git a/src/libstd/time.rs b/src/libstd/time.rs index 054450a5186..4e08301fe05 100644 --- a/src/libstd/time.rs +++ b/src/libstd/time.rs @@ -50,7 +50,7 @@ pub use core::time::Duration; /// instants). /// /// The size of an Instant struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// Example: /// @@ -92,7 +92,7 @@ pub struct Instant(time::Instant); /// or perhaps some other string representation. /// /// The size of a SystemTime struct may vary depending on the target operating -/// system, and may change between Rust releases. +/// system. /// /// [`Instant`]: ../../std/time/struct.Instant.html /// [`Result`]: ../../std/result/enum.Result.html From 1af952cc490b62a1f43f48c9fd809cf99aff2630 Mon Sep 17 00:00:00 2001 From: Phlosioneer Date: Tue, 20 Mar 2018 07:31:22 -0400 Subject: [PATCH 3/4] Remove StdioRaw doc additions, add backticks --- src/libstd/io/stdio.rs | 9 --------- src/libstd/net/addr.rs | 2 +- 2 files changed, 1 insertion(+), 10 deletions(-) diff --git a/src/libstd/io/stdio.rs b/src/libstd/io/stdio.rs index 9a4cde7e162..1f73054e3be 100644 --- a/src/libstd/io/stdio.rs +++ b/src/libstd/io/stdio.rs @@ -30,27 +30,18 @@ thread_local! { /// /// This handle is not synchronized or buffered in any fashion. Constructed via /// the `std::io::stdio::stdin_raw` function. -/// -/// The size of a StdinRaw struct may vary depending on the target operating -/// system. struct StdinRaw(stdio::Stdin); /// A handle to a raw instance of the standard output stream of this process. /// /// This handle is not synchronized or buffered in any fashion. Constructed via /// the `std::io::stdio::stdout_raw` function. -/// -/// The size of a StdoutRaw struct may vary depending on the target operating -/// system. struct StdoutRaw(stdio::Stdout); /// A handle to a raw instance of the standard output stream of this process. /// /// This handle is not synchronized or buffered in any fashion. Constructed via /// the `std::io::stdio::stderr_raw` function. -/// -/// The size of a StderrRaw struct may vary depending on the target operating -/// system. struct StderrRaw(stdio::Stderr); /// Constructs a new raw handle to the standard input of this process. diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index f985c1f2bc8..57efc3095fc 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -28,7 +28,7 @@ use slice; /// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and /// [`SocketAddrV6`]'s respective documentation for more details. /// -/// The size of a SocketAddr instance may vary depending on the target operating +/// The size of a `SocketAddr` instance may vary depending on the target operating /// system. /// /// [IP address]: ../../std/net/enum.IpAddr.html From efd04423c3300d79d0430c78602545ddf5b7f415 Mon Sep 17 00:00:00 2001 From: Phlosioneer Date: Sat, 24 Mar 2018 23:41:34 -0400 Subject: [PATCH 4/4] Add backticks --- src/libstd/net/addr.rs | 4 ++-- src/libstd/net/ip.rs | 6 +++--- src/libstd/time.rs | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/libstd/net/addr.rs b/src/libstd/net/addr.rs index 57efc3095fc..bc2c9f522d3 100644 --- a/src/libstd/net/addr.rs +++ b/src/libstd/net/addr.rs @@ -64,7 +64,7 @@ pub enum SocketAddr { /// /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. /// -/// The size of a SocketAddrV4 struct may vary depending on the target operating +/// The size of a `SocketAddrV4` struct may vary depending on the target operating /// system. /// /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 @@ -94,7 +94,7 @@ pub struct SocketAddrV4 { inner: c::sockaddr_in } /// /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. /// -/// The size of a SocketAddrV6 struct may vary depending on the target operating +/// The size of a `SocketAddrV6` struct may vary depending on the target operating /// system. /// /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 diff --git a/src/libstd/net/ip.rs b/src/libstd/net/ip.rs index 67b9e7a2f9d..031fae6d59b 100644 --- a/src/libstd/net/ip.rs +++ b/src/libstd/net/ip.rs @@ -26,7 +26,7 @@ use sys_common::{AsInner, FromInner}; /// This enum can contain either an [`Ipv4Addr`] or an [`Ipv6Addr`], see their /// respective documentation for more details. /// -/// The size of an IpAddr instance may vary depending on the target operating +/// The size of an `IpAddr` instance may vary depending on the target operating /// system. /// /// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html @@ -64,7 +64,7 @@ pub enum IpAddr { /// /// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. /// -/// The size of an Ipv4Addr struct may vary depending on the target operating +/// The size of an `Ipv4Addr` struct may vary depending on the target operating /// system. /// /// [IETF RFC 791]: https://tools.ietf.org/html/rfc791 @@ -99,7 +99,7 @@ pub struct Ipv4Addr { /// /// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. /// -/// The size of an Ipv6Addr struct may vary depending on the target operating +/// The size of an `Ipv6Addr` struct may vary depending on the target operating /// system. /// /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 diff --git a/src/libstd/time.rs b/src/libstd/time.rs index 4e08301fe05..7256ac43e27 100644 --- a/src/libstd/time.rs +++ b/src/libstd/time.rs @@ -49,7 +49,7 @@ pub use core::time::Duration; /// allows measuring the duration between two instants (or comparing two /// instants). /// -/// The size of an Instant struct may vary depending on the target operating +/// The size of an `Instant` struct may vary depending on the target operating /// system. /// /// Example: @@ -91,7 +91,7 @@ pub struct Instant(time::Instant); /// fixed point in time, a `SystemTime` can be converted to a human-readable time, /// or perhaps some other string representation. /// -/// The size of a SystemTime struct may vary depending on the target operating +/// The size of a `SystemTime` struct may vary depending on the target operating /// system. /// /// [`Instant`]: ../../std/time/struct.Instant.html