More comments.

Author: sunfishcode

src/imp/libc/io/poll_fd.rs

@@ -43,7 +43,10 @@ bitflags! {
     }
 }
 
-/// `struct pollfd`
+/// `struct pollfd`—File descriptor and flags for use with [`poll`].
+///
+/// [`poll`]: rustix::io::poll
+#[doc(alias = "pollfd")]
 #[derive(Clone, Debug)]
 #[repr(transparent)]
 pub struct PollFd<'fd> {

src/imp/linux_raw/io/poll_fd.rs

@@ -31,7 +31,10 @@ bitflags! {
     }
 }
 
-/// `struct pollfd`
+/// `struct pollfd`—File descriptor and flags for use with [`poll`].
+///
+/// [`poll`]: rustix::io::poll
+#[doc(alias = "pollfd")]
 #[repr(C)]
 #[derive(Debug, Clone)]
 pub struct PollFd<'fd> {

src/io/dup.rs

@@ -58,7 +58,7 @@ pub fn dup2<Fd: AsFd>(fd: &Fd, new: &OwnedFd) -> io::Result<()> {
 /// same underlying [file description] as the existing `OwnedFd` instance,
 /// closing `new` and reusing its file descriptor, with flags.
 ///
-/// `dup2_with` is the same as `dup2` but adds an additional flags operand.
+/// `dup2_with` is the same as [`dup2`] but adds an additional flags operand.
 ///
 /// # References
 ///  - [POSIX]

src/io/mmap.rs

@@ -184,7 +184,7 @@ pub unsafe fn mlock(ptr: *mut c_void, len: usize) -> io::Result<()> {
 /// `mlock2(ptr, len, flags)`—Lock memory into RAM, with
 /// flags.
 ///
-/// `mlock_with` is the same as `mlock` but adds an additional flags operand.
+/// `mlock_with` is the same as [`mlock`] but adds an additional flags operand.
 ///
 /// # Safety
 ///

src/io/owned_fd.rs

@@ -16,7 +16,7 @@ use core::fmt;
 use core::mem::{forget, ManuallyDrop};
 
 /// A wrapper around `io_lifetimes::OwnedFd` which closes the file descriptor
-/// using `rustix`'s own `close` rather than libc's `close`.
+/// using `rustix`'s own [`close`] rather than libc's `close`.
 #[repr(transparent)]
 pub struct OwnedFd {
     inner: ManuallyDrop<crate::imp::fd::OwnedFd>,

src/net/socket.rs

@@ -40,7 +40,8 @@ pub fn socket(domain: AddressFamily, type_: SocketType, protocol: Protocol) -> i
 /// however it is not safe in general to rely on this, as file descriptors
 /// may be unexpectedly allocated on other threads or in libraries.
 ///
-/// `socket_with` is the same as `socket` but adds an additional flags operand.
+/// `socket_with` is the same as [`socket`] but adds an additional flags
+/// operand.
 ///
 /// # References
 ///  - [POSIX]
@@ -200,7 +201,8 @@ pub fn accept<Fd: AsFd>(sockfd: &Fd) -> io::Result<OwnedFd> {
 /// descriptor, it is not safe in general to rely on this, as file descriptors
 /// may be unexpectedly allocated on other threads or in libraries.
 ///
-/// `accept_with` is the same as `accept` but adds an additional flags operand.
+/// `accept_with` is the same as [`accept`] but adds an additional flags
+/// operand.
 ///
 /// # References
 ///  - [POSIX]
@@ -238,8 +240,8 @@ pub fn acceptfrom<Fd: AsFd>(sockfd: &Fd) -> io::Result<(OwnedFd, SocketAddrAny)>
 ///
 /// Use [`accept_with`] if the peer address isn't needed.
 ///
-/// `acceptfrom_with` is the same as `acceptfrom` but adds an additional flags
-/// operand.
+/// `acceptfrom_with` is the same as [`acceptfrom`] but adds an additional
+/// flags operand.
 ///
 /// # References
 ///  - [POSIX]