From 2a887a47bf8b27e47ac76570fcc99f590b01ab1e Mon Sep 17 00:00:00 2001 From: Bruce Mitchener Date: Thu, 24 Oct 2024 00:04:39 +0700 Subject: [PATCH] Fix `clippy::doc_markdown` lints (#621) --- file-id/src/lib.rs | 8 ++++---- notify-debouncer-full/src/lib.rs | 8 ++++---- notify-debouncer-mini/src/lib.rs | 2 +- notify/src/config.rs | 12 ++++++------ notify/src/lib.rs | 28 ++++++++++++++-------------- notify/src/poll.rs | 14 +++++++------- 6 files changed, 36 insertions(+), 36 deletions(-) diff --git a/file-id/src/lib.rs b/file-id/src/lib.rs index 4a13b50a..3c0091fd 100644 --- a/file-id/src/lib.rs +++ b/file-id/src/lib.rs @@ -1,8 +1,8 @@ -//! Utility for reading inode numbers (Linux, MacOS) and file ids (Windows) that uniquely identify a file on a single computer. +//! Utility for reading inode numbers (Linux, macOS) and file ids (Windows) that uniquely identify a file on a single computer. //! -//! Modern file systems assign a unique ID to each file. On Linux and MacOS it is called an `inode number`, +//! Modern file systems assign a unique ID to each file. On Linux and macOS it is called an `inode number`, //! on Windows it is called a `file id` or `file index`. -//! Together with the `device id` (Linux, MacOS) or the `volume serial number` (Windows), +//! Together with the `device id` (Linux, macOS) or the `volume serial number` (Windows), //! a file or directory can be uniquely identified on a single computer at a given time. //! //! Keep in mind though, that IDs may be re-used at some point. @@ -36,7 +36,7 @@ use serde::{Deserialize, Serialize}; #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))] pub enum FileId { - /// Inode number, available on Linux and MacOS. + /// Inode number, available on Linux and macOS. #[cfg_attr(feature = "serde", serde(rename = "inode"))] Inode { /// Device ID diff --git a/notify-debouncer-full/src/lib.rs b/notify-debouncer-full/src/lib.rs index dfbe37f1..3ef448d7 100644 --- a/notify-debouncer-full/src/lib.rs +++ b/notify-debouncer-full/src/lib.rs @@ -3,7 +3,7 @@ //! * Only emits a single `Rename` event if the rename `From` and `To` events can be matched //! * Merges multiple `Rename` events //! * Takes `Rename` events into account and updates paths for events that occurred before the rename event, but which haven't been emitted, yet -//! * Optionally keeps track of the file system IDs all files and stitches rename events together (FSevents, Windows) +//! * Optionally keeps track of the file system IDs all files and stitches rename events together (macOS FS Events, Windows) //! * Emits only one `Remove` event when deleting a directory (inotify) //! * Doesn't emit duplicate create events //! * Doesn't emit `Modify` events after a `Create` event @@ -523,7 +523,7 @@ pub struct Debouncer { impl Debouncer { /// Stop the debouncer, waits for the event thread to finish. - /// May block for the duration of one tick_rate. + /// May block for the duration of one `tick_rate`. pub fn stop(mut self) { self.set_stop(); if let Some(t) = self.debouncer_thread.take() { @@ -607,7 +607,7 @@ impl Drop for Debouncer { /// /// Timeout is the amount of time after which a debounced event is emitted. /// -/// If tick_rate is None, notify will select a tick rate that is 1/4 of the provided timeout. +/// If `tick_rate` is `None`, notify will select a tick rate that is 1/4 of the provided timeout. pub fn new_debouncer_opt( timeout: Duration, tick_rate: Option, @@ -689,7 +689,7 @@ pub fn new_debouncer_opt( timeout: Duration, tick_rate: Option, diff --git a/notify-debouncer-mini/src/lib.rs b/notify-debouncer-mini/src/lib.rs index 84f30209..d4470b3f 100644 --- a/notify-debouncer-mini/src/lib.rs +++ b/notify-debouncer-mini/src/lib.rs @@ -264,7 +264,7 @@ impl DebounceDataInner { /// Updates the deadline if none is set or when batch mode is disabled and the current deadline would miss the next event. /// The new deadline is calculated based on the last event update time and the debounce timeout. /// - /// can't sub-function this due to event_map.drain() holding &mut self + /// can't sub-function this due to `event_map.drain()` holding `&mut self` fn check_deadline( batch_mode: bool, timeout: Duration, diff --git a/notify/src/config.rs b/notify/src/config.rs index a588eb78..94ddc65f 100644 --- a/notify/src/config.rs +++ b/notify/src/config.rs @@ -45,14 +45,14 @@ pub struct Config { } impl Config { - /// For the [PollWatcher](crate::PollWatcher) backend. + /// For the [`PollWatcher`](crate::PollWatcher) backend. /// /// Interval between each re-scan attempt. This can be extremely expensive for large /// file trees so it is recommended to measure and tune accordingly. /// /// The default poll frequency is 30 seconds. /// - /// This will enable automatic polling, overwriting [with_manual_polling](Config::with_manual_polling). + /// This will enable automatic polling, overwriting [`with_manual_polling()`](Config::with_manual_polling). pub fn with_poll_interval(mut self, dur: Duration) -> Self { // TODO: v7.0 break signature to option self.poll_interval = Some(dur); @@ -65,17 +65,17 @@ impl Config { self.poll_interval } - /// For the [PollWatcher](crate::PollWatcher) backend. + /// For the [`PollWatcher`](crate::PollWatcher) backend. /// - /// Disable automatic polling. Requires calling [crate::PollWatcher::poll] manually. + /// Disable automatic polling. Requires calling [`crate::PollWatcher::poll()`] manually. /// - /// This will disable automatic polling, overwriting [with_poll_interval](Config::with_poll_interval). + /// This will disable automatic polling, overwriting [`with_poll_interval()`](Config::with_poll_interval). pub fn with_manual_polling(mut self) -> Self { self.poll_interval = None; self } - /// For the [PollWatcher](crate::PollWatcher) backend. + /// For the [`PollWatcher`](crate::PollWatcher) backend. /// /// Optional feature that will evaluate the contents of changed files to determine if /// they have indeed changed using a fast hashing algorithm. This is especially important diff --git a/notify/src/lib.rs b/notify/src/lib.rs index e7e8f909..30b3b50a 100644 --- a/notify/src/lib.rs +++ b/notify/src/lib.rs @@ -34,14 +34,14 @@ //! Network mounted filesystems like NFS may not emit any events for notify to listen to. //! This applies especially to WSL programs watching windows paths ([issue #254](https://github.com/notify-rs/notify/issues/254)). //! -//! A workaround is the [PollWatcher] backend. +//! A workaround is the [`PollWatcher`] backend. //! -//! ### Docker with Linux on MacOS M1 +//! ### Docker with Linux on macOS M1 //! -//! Docker on macos M1 [throws](https://github.com/notify-rs/notify/issues/423) `Function not implemented (os error 38)`. -//! You have to manually use the [PollWatcher], as the native backend isn't available inside the emulation. +//! Docker on macOS M1 [throws](https://github.com/notify-rs/notify/issues/423) `Function not implemented (os error 38)`. +//! You have to manually use the [`PollWatcher`], as the native backend isn't available inside the emulation. //! -//! ### MacOS, FSEvents and unowned files +//! ### macOS, FSEvents and unowned files //! //! Due to the inner security model of FSEvents (see [FileSystemEventSecurity](https://developer.apple.com/library/mac/documentation/Darwin/Conceptual/FSEvents_ProgGuide/FileSystemEventSecurity/FileSystemEventSecurity.html)), //! some events cannot be observed easily when trying to follow files that do not @@ -62,7 +62,7 @@ //! ### Pseudo Filesystems like /proc, /sys //! //! Some filesystems like `/proc` and `/sys` on *nix do not emit change events or use correct file change dates. -//! To circumvent that problem you can use the [PollWatcher] with the `compare_contents` option. +//! To circumvent that problem you can use the [`PollWatcher`] with the `compare_contents` option. //! //! ### Linux: Bad File Descriptor / No space left on device //! @@ -76,7 +76,7 @@ //! sudo sysctl -p //! ``` //! -//! Note that the [PollWatcher] is not restricted by this limitation, so it may be an alternative if your users can't increase the limit. +//! Note that the [`PollWatcher`] is not restricted by this limitation, so it may be an alternative if your users can't increase the limit. //! //! ### Watching large directories //! @@ -287,7 +287,7 @@ pub enum WatcherKind { /// Type that can deliver file activity notifications /// -/// Watcher is implemented per platform using the best implementation available on that platform. +/// `Watcher` is implemented per platform using the best implementation available on that platform. /// In addition to such event driven implementations, a polling implementation is also provided /// that should work on any platform. pub trait Watcher { @@ -339,16 +339,16 @@ pub trait Watcher { Self: Sized; } -/// The recommended `Watcher` implementation for the current platform +/// The recommended [`Watcher`] implementation for the current platform #[cfg(any(target_os = "linux", target_os = "android"))] pub type RecommendedWatcher = INotifyWatcher; -/// The recommended `Watcher` implementation for the current platform +/// The recommended [`Watcher`] implementation for the current platform #[cfg(all(target_os = "macos", not(feature = "macos_kqueue")))] pub type RecommendedWatcher = FsEventWatcher; -/// The recommended `Watcher` implementation for the current platform +/// The recommended [`Watcher`] implementation for the current platform #[cfg(target_os = "windows")] pub type RecommendedWatcher = ReadDirectoryChangesWatcher; -/// The recommended `Watcher` implementation for the current platform +/// The recommended [`Watcher`] implementation for the current platform #[cfg(any( target_os = "freebsd", target_os = "openbsd", @@ -358,7 +358,7 @@ pub type RecommendedWatcher = ReadDirectoryChangesWatcher; all(target_os = "macos", feature = "macos_kqueue") ))] pub type RecommendedWatcher = KqueueWatcher; -/// The recommended `Watcher` implementation for the current platform +/// The recommended [`Watcher`] implementation for the current platform #[cfg(not(any( target_os = "linux", target_os = "android", @@ -372,7 +372,7 @@ pub type RecommendedWatcher = KqueueWatcher; )))] pub type RecommendedWatcher = PollWatcher; -/// Convenience method for creating the `RecommendedWatcher` for the current platform. +/// Convenience method for creating the [`RecommendedWatcher`] for the current platform. pub fn recommended_watcher(event_handler: F) -> Result where F: EventHandler, diff --git a/notify/src/poll.rs b/notify/src/poll.rs index 830b1ee1..a96af9cd 100644 --- a/notify/src/poll.rs +++ b/notify/src/poll.rs @@ -15,11 +15,11 @@ use std::{ time::Duration, }; -/// Event send for registered handler on initial directory scans +/// Event sent for registered handlers on initial directory scans pub type ScanEvent = crate::Result; -/// Handler trait for receivers of ScanEvent. -/// Very much the same as [EventHandler], but including the Result. +/// Handler trait for receivers of [`ScanEvent`]. +/// Very much the same as [`EventHandler`], but including the Result. /// /// See the full example for more information. pub trait ScanEventHandler: Send + 'static { @@ -482,7 +482,7 @@ pub struct PollWatcher { } impl PollWatcher { - /// Create a new [PollWatcher], configured as needed. + /// Create a new [`PollWatcher`], configured as needed. pub fn new(event_handler: F, config: Config) -> crate::Result { Self::with_opt::<_, ()>(event_handler, config, None) } @@ -495,7 +495,7 @@ impl PollWatcher { Ok(()) } - /// Create a new [PollWatcher] with an scan event handler. + /// Create a new [`PollWatcher`] with an scan event handler. /// /// `scan_fallback` is called on the initial scan with all files seen by the pollwatcher. pub fn with_initial_scan( @@ -506,7 +506,7 @@ impl PollWatcher { Self::with_opt(event_handler, config, Some(scan_callback)) } - /// create a new PollWatcher with all options + /// create a new [`PollWatcher`] with all options. fn with_opt( event_handler: F, config: Config, @@ -606,7 +606,7 @@ impl PollWatcher { } impl Watcher for PollWatcher { - /// Create a new [PollWatcher]. + /// Create a new [`PollWatcher`]. fn new(event_handler: F, config: Config) -> crate::Result { Self::new(event_handler, config) }