Miscellaneous documentation cleanups. (#929)

Author: sunfishcode

README.md

@@ -158,7 +158,7 @@ version of this crate.
 [`simple_libc`]: https://crates.io/crates/simple_libc
 [`uapi`]: https://crates.io/crates/uapi
 [`rusl`]: https://lib.rs/crates/rusl
-[`relibc`]: https://github.com/redox-os/relibc
+[`relibc`]: https://gitlab.redox-os.org/redox-os/relibc
 [`syscall`]: https://crates.io/crates/syscall
 [`sc`]: https://crates.io/crates/sc
 [`scall`]: https://crates.io/crates/scall

src/backend/libc/mount/types.rs

@@ -299,9 +299,9 @@ bitflags! {
 
 #[cfg(linux_kernel)]
 bitflags! {
-    /// `MS_*` constants for use with [`change_mount`].
+    /// `MS_*` constants for use with [`mount_change`].
     ///
-    /// [`change_mount`]: crate::mount::change_mount
+    /// [`mount_change`]: crate::mount::mount_change
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MountPropagationFlags: c::c_ulong {

src/backend/libc/time/types.rs

@@ -83,9 +83,11 @@ bitflags! {
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct TimerfdFlags: u32 {
         /// `TFD_NONBLOCK`
+        #[doc(alias = "TFD_NONBLOCK")]
         const NONBLOCK = bitcast!(c::TFD_NONBLOCK);
 
         /// `TFD_CLOEXEC`
+        #[doc(alias = "TFD_CLOEXEC")]
         const CLOEXEC = bitcast!(c::TFD_CLOEXEC);
 
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
@@ -102,10 +104,12 @@ bitflags! {
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct TimerfdTimerFlags: u32 {
         /// `TFD_TIMER_ABSTIME`
+        #[doc(alias = "TFD_TIMER_ABSTIME")]
         const ABSTIME = bitcast!(c::TFD_TIMER_ABSTIME);
 
         /// `TFD_TIMER_CANCEL_ON_SET`
         #[cfg(linux_kernel)]
+        #[doc(alias = "TFD_TIMER_CANCEL_ON_SET")]
         const CANCEL_ON_SET = bitcast!(c::TFD_TIMER_CANCEL_ON_SET);
 
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
@@ -127,6 +131,7 @@ pub enum TimerfdClockId {
     /// epoch, 1970-01-01T00:00:00Z. The clock is externally settable, so it is
     /// not monotonic. Successive reads may see decreasing times, so it isn't
     /// reliable for measuring durations.
+    #[doc(alias = "CLOCK_REALTIME")]
     Realtime = bitcast!(c::CLOCK_REALTIME),
 
     /// `CLOCK_MONOTONIC`—A clock that tells an abstract time.
@@ -137,26 +142,30 @@ pub enum TimerfdClockId {
     ///
     /// This clock does not advance while the system is suspended; see
     /// `Boottime` for a clock that does.
+    #[doc(alias = "CLOCK_MONOTONIC")]
     Monotonic = bitcast!(c::CLOCK_MONOTONIC),
 
     /// `CLOCK_BOOTTIME`—Like `Monotonic`, but advances while suspended.
     ///
     /// This clock is similar to `Monotonic`, but does advance while the system
     /// is suspended.
+    #[doc(alias = "CLOCK_BOOTTIME")]
     Boottime = bitcast!(c::CLOCK_BOOTTIME),
 
     /// `CLOCK_REALTIME_ALARM`—Like `Realtime`, but wakes a suspended system.
     ///
     /// This clock is like `Realtime`, but can wake up a suspended system.
     ///
     /// Use of this clock requires the `CAP_WAKE_ALARM` Linux capability.
+    #[doc(alias = "CLOCK_REALTIME_ALARM")]
     RealtimeAlarm = bitcast!(c::CLOCK_REALTIME_ALARM),
 
     /// `CLOCK_BOOTTIME_ALARM`—Like `Boottime`, but wakes a suspended system.
     ///
     /// This clock is like `Boottime`, but can wake up a suspended system.
     ///
     /// Use of this clock requires the `CAP_WAKE_ALARM` Linux capability.
+    #[doc(alias = "CLOCK_BOOTTIME_ALARM")]
     BoottimeAlarm = bitcast!(c::CLOCK_BOOTTIME_ALARM),
 }
 

src/backend/linux_raw/mount/types.rs

@@ -292,9 +292,9 @@ bitflags! {
 }
 
 bitflags! {
-    /// `MS_*` constants for use with [`change_mount`].
+    /// `MS_*` constants for use with [`mount_change`].
     ///
-    /// [`change_mount`]: crate::mount::change_mount
+    /// [`mount_change`]: crate::mount::mount_change
     #[repr(transparent)]
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct MountPropagationFlags: c::c_uint {

src/backend/linux_raw/runtime/syscalls.rs

@@ -300,6 +300,6 @@ pub(crate) fn exit_group(code: c::c_int) -> ! {
 
 #[inline]
 pub(crate) unsafe fn brk(addr: *mut c::c_void) -> io::Result<*mut c_void> {
-    // Don't mark this `readonly`, so that loads don't get reordered past it.
+    // This is non-`readonly`, to prevent loads from being reordered past it.
     ret_void_star(syscall!(__NR_brk, addr))
 }

src/backend/linux_raw/time/types.rs

@@ -16,9 +16,11 @@ bitflags! {
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct TimerfdFlags: c::c_uint {
         /// `TFD_NONBLOCK`
+        #[doc(alias = "TFD_NONBLOCK")]
         const NONBLOCK = linux_raw_sys::general::TFD_NONBLOCK;
 
         /// `TFD_CLOEXEC`
+        #[doc(alias = "TFD_CLOEXEC")]
         const CLOEXEC = linux_raw_sys::general::TFD_CLOEXEC;
 
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
@@ -34,9 +36,11 @@ bitflags! {
     #[derive(Copy, Clone, Eq, PartialEq, Hash, Debug)]
     pub struct TimerfdTimerFlags: c::c_uint {
         /// `TFD_TIMER_ABSTIME`
+        #[doc(alias = "TFD_TIMER_ABSTIME")]
         const ABSTIME = linux_raw_sys::general::TFD_TIMER_ABSTIME;
 
         /// `TFD_TIMER_CANCEL_ON_SET`
+        #[doc(alias = "TFD_TIMER_CANCEL_ON_SET")]
         const CANCEL_ON_SET = linux_raw_sys::general::TFD_TIMER_CANCEL_ON_SET;
 
         /// <https://docs.rs/bitflags/*/bitflags/#externally-defined-flags>
@@ -57,6 +61,7 @@ pub enum TimerfdClockId {
     /// epoch, 1970-01-01T00:00:00Z. The clock is externally settable, so it is
     /// not monotonic. Successive reads may see decreasing times, so it isn't
     /// reliable for measuring durations.
+    #[doc(alias = "CLOCK_REALTIME")]
     Realtime = linux_raw_sys::general::CLOCK_REALTIME,
 
     /// `CLOCK_MONOTONIC`—A clock that tells an abstract time.
@@ -67,25 +72,29 @@ pub enum TimerfdClockId {
     ///
     /// This clock does not advance while the system is suspended; see
     /// `Boottime` for a clock that does.
+    #[doc(alias = "CLOCK_MONOTONIC")]
     Monotonic = linux_raw_sys::general::CLOCK_MONOTONIC,
 
     /// `CLOCK_BOOTTIME`—Like `Monotonic`, but advances while suspended.
     ///
     /// This clock is similar to `Monotonic`, but does advance while the system
     /// is suspended.
+    #[doc(alias = "CLOCK_BOOTTIME")]
     Boottime = linux_raw_sys::general::CLOCK_BOOTTIME,
 
     /// `CLOCK_REALTIME_ALARM`—Like `Realtime`, but wakes a suspended system.
     ///
     /// This clock is like `Realtime`, but can wake up a suspended system.
     ///
     /// Use of this clock requires the `CAP_WAKE_ALARM` Linux capability.
+    #[doc(alias = "CLOCK_REALTIME_ALARM")]
     RealtimeAlarm = linux_raw_sys::general::CLOCK_REALTIME_ALARM,
 
     /// `CLOCK_BOOTTIME_ALARM`—Like `Boottime`, but wakes a suspended system.
     ///
     /// This clock is like `Boottime`, but can wake up a suspended system.
     ///
     /// Use of this clock requires the `CAP_WAKE_ALARM` Linux capability.
+    #[doc(alias = "CLOCK_BOOTTIME_ALARM")]
     BoottimeAlarm = linux_raw_sys::general::CLOCK_BOOTTIME_ALARM,
 }

src/clockid.rs

@@ -17,13 +17,16 @@ use crate::fd::BorrowedFd;
 #[non_exhaustive]
 pub enum ClockId {
     /// `CLOCK_REALTIME`
+    #[doc(alias = "CLOCK_REALTIME")]
     Realtime = bitcast!(c::CLOCK_REALTIME),
 
     /// `CLOCK_MONOTONIC`
+    #[doc(alias = "CLOCK_MONOTONIC")]
     Monotonic = bitcast!(c::CLOCK_MONOTONIC),
 
     /// `CLOCK_UPTIME`
     #[cfg(any(freebsdlike, target_os = "openbsd"))]
+    #[doc(alias = "CLOCK_UPTIME")]
     Uptime = c::CLOCK_UPTIME,
 
     /// `CLOCK_PROCESS_CPUTIME_ID`
@@ -33,6 +36,7 @@ pub enum ClockId {
         target_os = "redox",
         target_os = "vita"
     )))]
+    #[doc(alias = "CLOCK_PROCESS_CPUTIME_ID")]
     ProcessCPUTime = c::CLOCK_PROCESS_CPUTIME_ID,
 
     /// `CLOCK_THREAD_CPUTIME_ID`
@@ -42,18 +46,22 @@ pub enum ClockId {
         target_os = "redox",
         target_os = "vita"
     )))]
+    #[doc(alias = "CLOCK_THREAD_CPUTIME_ID")]
     ThreadCPUTime = c::CLOCK_THREAD_CPUTIME_ID,
 
     /// `CLOCK_REALTIME_COARSE`
     #[cfg(any(linux_kernel, target_os = "freebsd"))]
+    #[doc(alias = "CLOCK_REALTIME_COARSE")]
     RealtimeCoarse = c::CLOCK_REALTIME_COARSE,
 
     /// `CLOCK_MONOTONIC_COARSE`
     #[cfg(any(linux_kernel, target_os = "freebsd"))]
+    #[doc(alias = "CLOCK_MONOTONIC_COARSE")]
     MonotonicCoarse = c::CLOCK_MONOTONIC_COARSE,
 
     /// `CLOCK_MONOTONIC_RAW`
     #[cfg(linux_kernel)]
+    #[doc(alias = "CLOCK_MONOTONIC_RAW")]
     MonotonicRaw = c::CLOCK_MONOTONIC_RAW,
 
     /// `CLOCK_REALTIME_ALARM`, available on Linux >= 3.0
@@ -98,15 +106,19 @@ pub enum ClockId {
 #[non_exhaustive]
 pub enum ClockId {
     /// `CLOCK_REALTIME`
+    #[doc(alias = "CLOCK_REALTIME")]
     Realtime = c::CLOCK_REALTIME,
 
     /// `CLOCK_MONOTONIC`
+    #[doc(alias = "CLOCK_MONOTONIC")]
     Monotonic = c::CLOCK_MONOTONIC,
 
     /// `CLOCK_PROCESS_CPUTIME_ID`
+    #[doc(alias = "CLOCK_PROCESS_CPUTIME_ID")]
     ProcessCPUTime = c::CLOCK_PROCESS_CPUTIME_ID,
 
     /// `CLOCK_THREAD_CPUTIME_ID`
+    #[doc(alias = "CLOCK_THREAD_CPUTIME_ID")]
     ThreadCPUTime = c::CLOCK_THREAD_CPUTIME_ID,
 }
 
@@ -129,10 +141,12 @@ pub enum DynamicClockId<'a> {
 
     /// `CLOCK_REALTIME_ALARM`, available on Linux >= 3.0
     #[cfg(linux_kernel)]
+    #[doc(alias = "CLOCK_REALTIME_ALARM")]
     RealtimeAlarm,
 
     /// `CLOCK_TAI`, available on Linux >= 3.10
     #[cfg(linux_kernel)]
+    #[doc(alias = "CLOCK_TAI")]
     Tai,
 
     /// `CLOCK_BOOTTIME`, available on Linux >= 2.6.39
@@ -142,9 +156,11 @@ pub enum DynamicClockId<'a> {
         target_os = "fuchsia",
         target_os = "openbsd"
     ))]
+    #[doc(alias = "CLOCK_BOOTTIME")]
     Boottime,
 
     /// `CLOCK_BOOTTIME_ALARM`, available on Linux >= 2.6.39
     #[cfg(any(linux_kernel, target_os = "fuchsia"))]
+    #[doc(alias = "CLOCK_BOOTTIME_ALARM")]
     BoottimeAlarm,
 }

src/ioctl/bsd.rs

@@ -1,4 +1,4 @@
-//! `ioctl` opcode behavior for Linux platforms.
+//! `ioctl` opcode behavior for BSD platforms.
 
 use super::{Direction, RawOpcode};