Clarify network byte order conversions for integer / IP address conversions.
Opened primarily to address https://github.com/rust-lang/rust/issues/48819.
Also added a few other conversion docs/examples.
This patch makes it clear in std::process::Child::kill()'s API
documentation that an error is returned if the child process has
already cleanly exited. This is implied by the example, but not
called out explicitly.
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) <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#43601.
Reduce scope of unsafe block in sun_path_offset
I reduced the scope of the unsafe block to the `uninitialized` call which is the only actual unsafe bit.
Document format_args! / Arguments<'a> behavior wrt. Display and Debug
This is a follow up PR to #49067 , this documents the behavior of `format_args!` (i.e: `Argument<'a>`) wrt. `Display` and `Debug`.
r? @steveklabnik
