Update the public comment for fd and simplify the fd module. (#1420)

Avoid redundantly listing the items of the `fd` module. And use the
normal Windows function and type names when in Windows-specific code.

Author: sunfishcode

src/backend/libc/io/windows_syscalls.rs

@@ -4,7 +4,6 @@ use crate::backend::c;
 #[cfg(feature = "try_close")]
 use crate::backend::conv::ret;
 use crate::backend::conv::{borrowed_fd, ret_c_int, ret_send_recv, send_recv_len};
-use crate::backend::fd::LibcFd;
 use crate::fd::{BorrowedFd, RawFd};
 use crate::io;
 use crate::ioctl::{IoctlOutput, Opcode};
@@ -32,12 +31,12 @@ pub(crate) fn write(fd: BorrowedFd<'_>, buf: &[u8]) -> io::Result<usize> {
 }
 
 pub(crate) unsafe fn close(raw_fd: RawFd) {
-    let _ = c::close(raw_fd as LibcFd);
+    let _ = c::closesocket(raw_fd as c::SOCKET);
 }
 
 #[cfg(feature = "try_close")]
 pub(crate) unsafe fn try_close(raw_fd: RawFd) -> io::Result<()> {
-    ret(c::close(raw_fd as LibcFd))
+    ret(c::closesocket(raw_fd as c::SOCKET))
 }
 
 #[inline]

src/backend/libc/mod.rs

@@ -15,6 +15,9 @@ mod conv;
 
 #[cfg(windows)]
 pub(crate) mod fd {
+    // Re-export `AsSocket` etc. too, as users can't implement `AsFd` etc. on
+    // Windows due to them having blanket impls on Windows, so users must
+    // implement `AsSocket` etc.
     pub use crate::maybe_polyfill::os::windows::io::{
         AsRawSocket, AsSocket, BorrowedSocket as BorrowedFd, FromRawSocket, IntoRawSocket,
         OwnedSocket as OwnedFd, RawSocket as RawFd,
@@ -90,9 +93,7 @@ pub(crate) mod fd {
 }
 #[cfg(not(windows))]
 pub(crate) mod fd {
-    pub use crate::maybe_polyfill::os::fd::{
-        AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd,
-    };
+    pub use crate::maybe_polyfill::os::fd::*;
     #[allow(unused_imports)]
     pub(crate) use RawFd as LibcFd;
 }

src/backend/linux_raw/mod.rs

@@ -78,11 +78,8 @@ pub(crate) mod thread;
 #[cfg(feature = "time")]
 pub(crate) mod time;
 
-pub(crate) mod fd {
-    pub use crate::maybe_polyfill::os::fd::{
-        AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd,
-    };
-}
+// Re-export the maybe-polyfill `core::os::fd`.
+pub(crate) use crate::maybe_polyfill::os::fd;
 
 // The linux_raw backend doesn't use actual libc, so we define selected
 // libc-like definitions in a module called `c`.

src/lib.rs

@@ -193,18 +193,19 @@ mod backend;
 
 /// Export the `*Fd` types and traits that are used in rustix's public API.
 ///
-/// Users can use this to avoid needing to import anything else to use the same
-/// versions of these types and traits.
+/// This module exports the types and traits from [`std::os::fd`], or polyills
+/// on Rust < 1.66 or on Windows.
+///
+/// On Windows, the polyfill consists of aliases of the socket types and
+/// traits, For example, [`OwnedSocket`] is aliased to `OwnedFd`, and so on,
+/// and there are blanket impls for `AsFd` etc. that map to `AsSocket` impls.
+/// These blanket impls suffice for using the traits, however not for
+/// implementing them, so this module also exports `AsSocket` and the other
+/// traits as-is so that users can implement them if needed.
+///
+/// [`OwnedSocket`]: https://doc.rust-lang.org/stable/std/os/windows/io/struct.OwnedSocket.html
 pub mod fd {
-    use super::backend;
-
-    // Re-export `AsSocket` etc. too, as users can't implement `AsFd` etc. on
-    // Windows due to them having blanket impls on Windows, so users must
-    // implement `AsSocket` etc.
-    #[cfg(windows)]
-    pub use backend::fd::{AsRawSocket, AsSocket, FromRawSocket, IntoRawSocket};
-
-    pub use backend::fd::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd};
+    pub use super::backend::fd::*;
 }
 
 // The public API modules.

src/maybe_polyfill/no_std/os/windows/io/socket.rs

@@ -7,7 +7,6 @@
 
 use super::raw::*;
 use crate::backend::c;
-use crate::backend::fd::LibcFd as LibcSocket;
 use core::fmt;
 use core::marker::PhantomData;
 use core::mem::forget;
@@ -132,7 +131,7 @@ impl Drop for OwnedSocket {
     #[inline]
     fn drop(&mut self) {
         unsafe {
-            let _ = c::closesocket(self.socket as LibcSocket);
+            let _ = c::closesocket(self.socket as c::SOCKET);
         }
     }
 }