Rollup merge of rust-lang#48932 - Phlosioneer:43601-document-opaque-s…

…ize, r=KodrAus

Document when types have OS-dependent sizes

As per issue rust-lang#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) <name> struct may vary depending on the target
operating system, and may change between Rust releases.
```

For enums, I used "instance" instead of "struct".

I added documentation to these types:
```
- std::time::Instant						(contains sys::time::Instant)
- std::time::SystemTime						(contains sys::time::SystemTime)

- std::io::StdinRaw							(contains sys::stdio::Stdin)
- std::io::StdoutRaw						(contains sys::stdio::Stdout)
- std::io::Stderr							(contains sys::stdio::Stderr)

- std::net::addr::SocketAddrV4				(contains sys::net::netc::sockaddr_in)
- std::net::addr::SocketAddrV6				(contains sys::net::netc::sockaddr_in6)
- std::net::addr::SocketAddr				(contains std::net::addr::SocketAddrV4 and SocketAddrV6)
- std::net::ip::Ipv4Addr					(contains sys::net::netc::in_addr)
- std::net::ip::Ipv6Addr					(contains sys::net::netc::in6_addr)
- std::net::ip::IpAddr						(contains std::net::ip::Ipv4Addr and Ipv6Addr)
```

I also found that these types varied in size; however, I don't think they need documentation, as it's already fairly obvious that they change based on different OS's:

```
- std::fs::DirBuilder						(contains sys::fs::DirBuilder)
- std::fs::FileType							(contains sys::fs::FileType)
- std::fs::Permissions						(contains sys::fs::FilePermissions)
- std::fs::OpenOptions						(contains sys::fs::OpenOptions)
- std::fs::DirEntry							(contains sys::fs::DirEntry)
- std::fs::ReadDir							(contains sys::fs::ReadDir)
- std::fs::Metadata							(contains sys::fs::FileAttr)
- std::fs::File								(contains sys::fs::File)

- std::process::Child						(contains sys::process::Process)
- std::process::ChildStdin					(contains sys::process::AnonPipe)
- std::process::ChildStdout					(contains sys::process::AnonPipe)
- std::process::ChildStderr					(contains sys::process::AnonPipe)
- std::process::Command						(contains sys::process::Command)
- std::process::Stdio						(contains sys::process::Stdio)
- std::process::ExitStatus					(contains sys::process::ExitStatus)
- std::process::Output						(contains std::process::ExitStatus)

- std::sys_common::condvar::Condvar			(contains sys::condvar::Condvar)
- std::sys_common::mutex::Mutex				(contains sys::mutex::Mutex)
- std::sys_common::net::LookupHost			(contains sys::net::netc::addrinfo)
- std::sys_common::net::TcpStream			(contains sys::net::Socket)
- std::sys_common::net::TcpListener			(contains sys::net::Socket)
- std::sys_common::net::UdpSocket			(contains sys::net::Socket)
- std::sys_common::remutex::ReentrantMutex	(contains sys::mutex::ReentrantMutex)
- std::sys_common::rwlock::RWLock			(contains sys::rwlock::RWLock)
- std::sys_common::thread_local::Key		(contains sys::thread_local::Key)
```
Maybe we should just put a comment about the size of structs in the module-level docs for `fs`, `process`, and `sys_common`?

If anyone can think of other types that can change size, comment below. I'm also open to changing the wording.

closes rust-lang#43601.

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.
+///
 /// [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.
+///
 /// [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.
+///
 /// [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

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.
+///
 /// [`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.
+///
 /// [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.
+///
 /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291
 /// [`IpAddr`]: ../../std/net/enum.IpAddr.html
 ///

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.
+///
 /// 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.
+///
 /// [`Instant`]: ../../std/time/struct.Instant.html
 /// [`Result`]: ../../std/result/enum.Result.html
 /// [`Duration`]: ../../std/time/struct.Duration.html