Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: link to rust items by name #213

Merged
merged 1 commit into from
Feb 9, 2024
Merged

docs: link to rust items by name #213

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 11 additions & 47 deletions src/events.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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;
}
}
Expand Down
26 changes: 9 additions & 17 deletions src/inotify.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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())
}
Expand Down Expand Up @@ -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>>
{
Expand Down Expand Up @@ -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>>
{
Expand Down Expand Up @@ -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`
Expand Down
1 change: 0 additions & 1 deletion src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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


Expand Down
5 changes: 0 additions & 5 deletions src/stream.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>,
Expand All @@ -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())
}
Expand Down
6 changes: 3 additions & 3 deletions src/util.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand All @@ -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()`.
///
Expand Down
Loading
Loading