Document os-specific types in libstd may have different representations #43601
Labels
A-docs
Area: documentation for any part of the project, including the compiler, standard library, and tools
C-enhancement
Category: An issue proposing an enhancement or a PR with one.
P-medium
Medium priority
Comments
alexcrichton
added
the
A-docs
Mark-Simulacrum
added
the
C-enhancement
5 tasks
|
triage: tagging p-medium, we should review these docs |
Phlosioneer
added a commit
to Phlosioneer/rust
that referenced
this issue
Mar 11, 2018
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".
|
Made a PR for this; comments welcome! |
kennytm
added a commit
to kennytm/rust
that referenced
this issue
Mar 26, 2018
…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.
TimNN
added a commit
to TimNN/rust
that referenced
this issue
Mar 26, 2018
…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.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Spawned off #43332 it was decided that we should document that OS-specific types may have different representations in the standard library. Things like
size_ofandalign_ofmay be different depending on the platform you're working on.The text was updated successfully, but these errors were encountered: