docs: link to rust items by name

- For items that are in scope, remove the explicit html path. - For items not in scope, link to them by a rust path that does work (e.g. `crate::Watches` or `libc::read`). - Fix incorrect reference `WatchMask::IGNORED` -> `EventMask::IGNORED`. - Replace verbose `[https://some-url/](https://some-url/)` with the equivalent `<https://some-url/>`. This fixes many broken links (some always broken, some only broken on docs.rs), and makes them more robust in the future (rustdoc emits warnings most items that don't resolve.)
hannobraun · Feb 9, 2024 · 238b947 · 238b947
1 parent 39b6429
commit 238b947
Show file tree

Hide file tree

Showing 6 changed files with 46 additions and 160 deletions.
diff --git a/src/events.rs b/src/events.rs
@@ -19,8 +19,8 @@ use crate::watches::WatchDescriptor;
 /// Allows for iteration over the events returned by
 /// [`Inotify::read_events_blocking`] or [`Inotify::read_events`].
 ///
-/// [`Inotify::read_events_blocking`]: struct.Inotify.html#method.read_events_blocking
-/// [`Inotify::read_events`]: struct.Inotify.html#method.read_events
+/// [`Inotify::read_events_blocking`]: crate::Inotify::read_events_blocking
+/// [`Inotify::read_events`]: crate::Inotify::read_events
 #[derive(Debug)]
 pub struct Events<'a> {
     fd       : Weak<FdGuard>,
@@ -66,9 +66,9 @@ impl<'a> Iterator for Events<'a> {
 /// retrieve events, call [`Inotify::read_events_blocking`] or
 /// [`Inotify::read_events`].
 ///
-/// [`Watches::add`]: struct.Watches.html#method.add
-/// [`Inotify::read_events_blocking`]: struct.Inotify.html#method.read_events_blocking
-/// [`Inotify::read_events`]: struct.Inotify.html#method.read_events
+/// [`Watches::add`]: crate::Watches::add
+/// [`Inotify::read_events_blocking`]: crate::Inotify::read_events_blocking
+/// [`Inotify::read_events`]: crate::Inotify::read_events
 #[derive(Clone, Debug)]
 pub struct Event<S> {
     /// Identifies the watch this event originates from
@@ -79,9 +79,8 @@ pub struct Event<S> {
     /// [`Watches::remove`], thereby preventing future events of this type
     /// from being created.
     ///
-    /// [`WatchDescriptor`]: struct.WatchDescriptor.html
-    /// [`Watches::add`]: struct.Watches.html#method.add
-    /// [`Watches::remove`]: struct.Watches.html#method.remove
+    /// [`Watches::add`]: crate::Watches::add
+    /// [`Watches::remove`]: crate::Watches::remove
     pub wd: WatchDescriptor,
 
     /// Indicates what kind of event this is
@@ -93,8 +92,8 @@ pub struct Event<S> {
     /// [`MOVED_TO`]. The `cookie` field will be the same for both of them,
     /// thereby making is possible to connect the event pair.
     ///
-    /// [`MOVED_FROM`]: event_mask/constant.MOVED_FROM.html
-    /// [`MOVED_TO`]: event_mask/constant.MOVED_TO.html
+    /// [`MOVED_FROM`]: EventMask::MOVED_FROM
+    /// [`MOVED_TO`]: EventMask::MOVED_TO
     pub cookie: u32,
 
     /// The name of the file the event originates from
@@ -231,8 +230,6 @@ bitflags! {
     /// its associated constants.
     ///
     /// Please refer to the documentation of [`Event`] for a usage example.
-    ///
-    /// [`Event`]: struct.Event.html
     #[derive(PartialEq, Eq, PartialOrd, Ord, Hash, Debug, Clone, Copy)]
     pub struct EventMask: u32 {
         /// File was accessed
@@ -241,8 +238,6 @@ bitflags! {
         /// inside the directory, not the directory itself.
         ///
         /// See [`inotify_sys::IN_ACCESS`].
-        ///
-        /// [`inotify_sys::IN_ACCESS`]: ../inotify_sys/constant.IN_ACCESS.html
         const ACCESS = ffi::IN_ACCESS;
 
         /// Metadata (permissions, timestamps, ...) changed
@@ -251,8 +246,6 @@ bitflags! {
         /// directory itself, as well as objects inside the directory.
         ///
         /// See [`inotify_sys::IN_ATTRIB`].
-        ///
-        /// [`inotify_sys::IN_ATTRIB`]: ../inotify_sys/constant.IN_ATTRIB.html
         const ATTRIB = ffi::IN_ATTRIB;
 
         /// File opened for writing was closed
@@ -261,8 +254,6 @@ bitflags! {
         /// inside the directory, not the directory itself.
         ///
         /// See [`inotify_sys::IN_CLOSE_WRITE`].
-        ///
-        /// [`inotify_sys::IN_CLOSE_WRITE`]: ../inotify_sys/constant.IN_CLOSE_WRITE.html
         const CLOSE_WRITE = ffi::IN_CLOSE_WRITE;
 
         /// File or directory not opened for writing was closed
@@ -271,8 +262,6 @@ bitflags! {
         /// directory itself, as well as objects inside the directory.
         ///
         /// See [`inotify_sys::IN_CLOSE_NOWRITE`].
-        ///
-        /// [`inotify_sys::IN_CLOSE_NOWRITE`]: ../inotify_sys/constant.IN_CLOSE_NOWRITE.html
         const CLOSE_NOWRITE = ffi::IN_CLOSE_NOWRITE;
 
         /// File/directory created in watched directory
@@ -281,25 +270,17 @@ bitflags! {
         /// inside the directory, not the directory itself.
         ///
         /// See [`inotify_sys::IN_CREATE`].
-        ///
-        /// [`inotify_sys::IN_CREATE`]: ../inotify_sys/constant.IN_CREATE.html
         const CREATE = ffi::IN_CREATE;
 
         /// File/directory deleted from watched directory
         ///
         /// When watching a directory, this event is only triggered for objects
         /// inside the directory, not the directory itself.
-        ///
-        /// See [`inotify_sys::IN_DELETE`].
-        ///
-        /// [`inotify_sys::IN_DELETE`]: ../inotify_sys/constant.IN_DELETE.html
         const DELETE = ffi::IN_DELETE;
 
         /// Watched file/directory was deleted
         ///
         /// See [`inotify_sys::IN_DELETE_SELF`].
-        ///
-        /// [`inotify_sys::IN_DELETE_SELF`]: ../inotify_sys/constant.IN_DELETE_SELF.html
         const DELETE_SELF = ffi::IN_DELETE_SELF;
 
         /// File was modified
@@ -308,15 +289,11 @@ bitflags! {
         /// inside the directory, not the directory itself.
         ///
         /// See [`inotify_sys::IN_MODIFY`].
-        ///
-        /// [`inotify_sys::IN_MODIFY`]: ../inotify_sys/constant.IN_MODIFY.html
         const MODIFY = ffi::IN_MODIFY;
 
         /// Watched file/directory was moved
         ///
         /// See [`inotify_sys::IN_MOVE_SELF`].
-        ///
-        /// [`inotify_sys::IN_MOVE_SELF`]: ../inotify_sys/constant.IN_MOVE_SELF.html
         const MOVE_SELF = ffi::IN_MOVE_SELF;
 
         /// File was renamed/moved; watched directory contained old name
@@ -325,8 +302,6 @@ bitflags! {
         /// inside the directory, not the directory itself.
         ///
         /// See [`inotify_sys::IN_MOVED_FROM`].
-        ///
-        /// [`inotify_sys::IN_MOVED_FROM`]: ../inotify_sys/constant.IN_MOVED_FROM.html
         const MOVED_FROM = ffi::IN_MOVED_FROM;
 
         /// File was renamed/moved; watched directory contains new name
@@ -335,8 +310,6 @@ bitflags! {
         /// inside the directory, not the directory itself.
         ///
         /// See [`inotify_sys::IN_MOVED_TO`].
-        ///
-        /// [`inotify_sys::IN_MOVED_TO`]: ../inotify_sys/constant.IN_MOVED_TO.html
         const MOVED_TO = ffi::IN_MOVED_TO;
 
         /// File or directory was opened
@@ -345,8 +318,6 @@ bitflags! {
         /// directory itself, as well as objects inside the directory.
         ///
         /// See [`inotify_sys::IN_OPEN`].
-        ///
-        /// [`inotify_sys::IN_OPEN`]: ../inotify_sys/constant.IN_OPEN.html
         const OPEN = ffi::IN_OPEN;
 
         /// Watch was removed
@@ -357,38 +328,31 @@ bitflags! {
         ///
         /// See [`inotify_sys::IN_IGNORED`].
         ///
-        /// [`inotify_sys::IN_IGNORED`]: ../inotify_sys/constant.IN_IGNORED.html
+        /// [`Watches::remove`]: crate::Watches::remove
         const IGNORED = ffi::IN_IGNORED;
 
         /// Event related to a directory
         ///
         /// The subject of the event is a directory.
         ///
         /// See [`inotify_sys::IN_ISDIR`].
-        ///
-        /// [`inotify_sys::IN_ISDIR`]: ../inotify_sys/constant.IN_ISDIR.html
         const ISDIR = ffi::IN_ISDIR;
 
         /// Event queue overflowed
         ///
         /// The event queue has overflowed and events have presumably been lost.
         ///
         /// See [`inotify_sys::IN_Q_OVERFLOW`].
-        ///
-        /// [`inotify_sys::IN_Q_OVERFLOW`]: ../inotify_sys/constant.IN_Q_OVERFLOW.html
         const Q_OVERFLOW = ffi::IN_Q_OVERFLOW;
 
         /// File system containing watched object was unmounted.
         /// File system was unmounted
         ///
         /// The file system that contained the watched object has been
-        /// unmounted. An event with [`WatchMask::IGNORED`] will subsequently be
+        /// unmounted. An event with [`EventMask::IGNORED`] will subsequently be
         /// generated for the same watch descriptor.
         ///
         /// See [`inotify_sys::IN_UNMOUNT`].
-        ///
-        /// [`WatchMask::IGNORED`]: #associatedconstant.IGNORED
-        /// [`inotify_sys::IN_UNMOUNT`]: ../inotify_sys/constant.IN_UNMOUNT.html
         const UNMOUNT = ffi::IN_UNMOUNT;
     }
 }

diff --git a/src/inotify.rs b/src/inotify.rs
@@ -47,7 +47,7 @@ use crate::stream::EventStream;
 /// Please refer to the [top-level documentation] for further details and a
 /// usage example.
 ///
-/// [top-level documentation]: index.html
+/// [top-level documentation]: crate
 #[derive(Debug)]
 pub struct Inotify {
     fd: Arc<FdGuard>,
@@ -80,10 +80,9 @@ impl Inotify {
     ///     .expect("Failed to initialize an inotify instance");
     /// ```
     ///
-    /// [`Inotify`]: struct.Inotify.html
-    /// [`inotify_init1`]: ../inotify_sys/fn.inotify_init1.html
-    /// [`IN_CLOEXEC`]: ../inotify_sys/constant.IN_CLOEXEC.html
-    /// [`IN_NONBLOCK`]: ../inotify_sys/constant.IN_NONBLOCK.html
+    /// [`inotify_init1`]: inotify_sys::inotify_init1
+    /// [`IN_CLOEXEC`]: inotify_sys::IN_CLOEXEC
+    /// [`IN_NONBLOCK`]: inotify_sys::IN_NONBLOCK
     pub fn init() -> io::Result<Inotify> {
         let fd = unsafe {
             // Initialize inotify and pass both `IN_CLOEXEC` and `IN_NONBLOCK`.
@@ -118,9 +117,6 @@ impl Inotify {
 
     /// Gets an interface that allows adding and removing watches.
     /// See [`Watches::add`] and [`Watches::remove`].
-    ///
-    /// [`Watches::add`]: struct.Watches.html#method.add
-    /// [`Watches::remove`]: struct.Watches.html#method.remove
     pub fn watches(&self) -> Watches {
         Watches::new(self.fd.clone())
     }
@@ -148,9 +144,6 @@ impl Inotify {
     /// This method calls [`Inotify::read_events`] internally and behaves
     /// essentially the same, apart from the blocking behavior. Please refer to
     /// the documentation of [`Inotify::read_events`] for more information.
-    ///
-    /// [`Inotify::read_events`]: struct.Inotify.html#method.read_events
-    /// [`read`]: ../libc/fn.read.html
     pub fn read_events_blocking<'a>(&mut self, buffer: &'a mut [u8])
         -> io::Result<Events<'a>>
     {
@@ -224,10 +217,10 @@ impl Inotify {
     /// }
     /// ```
     ///
-    /// [`read_events_blocking`]: struct.Inotify.html#method.read_events_blocking
-    /// [`read`]: ../libc/fn.read.html
-    /// [`ErrorKind::UnexpectedEof`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.UnexpectedEof
-    /// [`ErrorKind::InvalidInput`]: https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput
+    /// [`read_events_blocking`]: Self::read_events_blocking
+    /// [`read`]: libc::read
+    /// [`ErrorKind::UnexpectedEof`]: std::io::ErrorKind::UnexpectedEof
+    /// [`ErrorKind::InvalidInput`]: std::io::ErrorKind::InvalidInput
     pub fn read_events<'a>(&mut self, buffer: &'a mut [u8])
         -> io::Result<Events<'a>>
     {
@@ -335,8 +328,7 @@ impl Inotify {
     ///     .expect("Failed to close inotify instance");
     /// ```
     ///
-    /// [`Inotify`]: struct.Inotify.html
-    /// [`close`]: ../libc/fn.close.html
+    /// [`close`]: libc::close
     pub fn close(self) -> io::Result<()> {
         // `self` will be dropped when this method returns. If this is the only
         // owner of `fd`, the `Arc` will also be dropped. The `Drop`

diff --git a/src/lib.rs b/src/lib.rs
@@ -63,7 +63,6 @@
 //!
 //! [inotify-rs]: https://crates.io/crates/inotify
 //! [inotify]: https://en.wikipedia.org/wiki/Inotify
-//! [`Inotify`]: struct.Inotify.html
 //! [inotify man pages]: http://man7.org/linux/man-pages/man7/inotify.7.html
 
 

diff --git a/src/stream.rs b/src/stream.rs
@@ -18,8 +18,6 @@ use crate::watches::Watches;
 /// Stream of inotify events
 ///
 /// Allows for streaming events returned by [`Inotify::into_event_stream`].
-///
-/// [`Inotify::into_event_stream`]: struct.Inotify.html#method.into_event_stream
 #[derive(Debug)]
 pub struct EventStream<T> {
     fd: AsyncFd<ArcFdGuard>,
@@ -44,9 +42,6 @@ where
 
     /// Returns an instance of `Watches` to add and remove watches.
     /// See [`Watches::add`] and [`Watches::remove`].
-    ///
-    /// [`Watches::add`]: struct.Watches.html#method.add
-    /// [`Watches::remove`]: struct.Watches.html#method.remove
     pub fn watches(&self) -> Watches {
         Watches::new(self.fd.get_ref().0.clone())
     }

diff --git a/src/util.rs b/src/util.rs
@@ -29,7 +29,7 @@ pub fn read_into_buffer(fd: RawFd, buffer: &mut [u8]) -> isize {
 /// can be calculated using this formula:
 /// `sizeof(struct inotify_event) + NAME_MAX + 1`
 ///
-/// See: [https://man7.org/linux/man-pages/man7/inotify.7.html](https://man7.org/linux/man-pages/man7/inotify.7.html)
+/// See: <https://man7.org/linux/man-pages/man7/inotify.7.html>
 ///
 /// The NAME_MAX size formula is:
 /// `ABSOLUTE_PARENT_PATH_LEN + 1 + 255`
@@ -39,11 +39,11 @@ pub fn read_into_buffer(fd: RawFd, buffer: &mut [u8]) -> isize {
 /// or for the root directory.
 /// - Add the maximum number of chars in a filename, 255.
 ///
-/// See: [https://github.com/torvalds/linux/blob/master/include/uapi/linux/limits.h](https://github.com/torvalds/linux/blob/master/include/uapi/linux/limits.h)
+/// See: <https://github.com/torvalds/linux/blob/master/include/uapi/linux/limits.h>
 ///
 /// Unfortunately, we can't just do the same with max path length itself.
 ///
-/// See: [https://eklitzke.org/path-max-is-tricky](https://eklitzke.org/path-max-is-tricky)
+/// See: <https://eklitzke.org/path-max-is-tricky>
 ///
 /// This function is really just a fallible wrapper around `get_absolute_path_buffer_size()`.
 ///