From 5c63a990130ed21b17a50cdb1888e115a1d5aa4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?F=C3=A9lix=20Saparelli?= Date: Sat, 18 Mar 2023 23:23:46 +1300 Subject: [PATCH] Fix and adjust docs (#530) --- .gitattributes | 2 + crates/cli/src/args.rs | 2 +- crates/events/README.md | 10 ++++- crates/events/src/lib.rs | 8 +--- crates/ignore-files/src/discover.rs | 2 +- crates/ignore-files/src/error.rs | 2 +- crates/ignore-files/src/filter.rs | 10 ++--- crates/lib/src/error/runtime.rs | 56 ++++++++++++++++++++++++++++ crates/lib/src/lib.rs | 3 -- crates/signals/README.md | 1 + crates/signals/src/lib.rs | 20 ++++------ doc/watchexec.1 | 2 +- doc/watchexec.1.md | 2 +- doc/watchexec.1.pdf | Bin 41722 -> 41715 bytes 14 files changed, 85 insertions(+), 35 deletions(-) diff --git a/.gitattributes b/.gitattributes index 8d93c93..30b27be 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1 +1,3 @@ Cargo.lock merge=binary +doc/watchexec.* merge=binary +completions/* merge=binary diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs index 974430a..1706f4c 100644 --- a/crates/cli/src/args.rs +++ b/crates/cli/src/args.rs @@ -16,7 +16,7 @@ include!(env!("BOSION_PATH")); /// change is detected (among other event sources). By default, watchexec uses efficient /// kernel-level mechanisms to watch for changes. /// -/// At startup, the specified is run once, and watchexec begins monitoring for changes. +/// At startup, the specified command is run once, and watchexec begins monitoring for changes. /// /// Examples: /// diff --git a/crates/events/README.md b/crates/events/README.md index 08a2516..070b285 100644 --- a/crates/events/README.md +++ b/crates/events/README.md @@ -9,8 +9,14 @@ _Watchexec's event types._ [docs]: https://docs.rs/watchexec-events [license]: ../../LICENSE -This is particularly useful if you're building a tool that runs under Watchexec, and want to easily -read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`). +Fundamentally, events in watchexec have three purposes: + +1. To trigger the launch, restart, or other interruption of a process; +2. To be filtered upon according to whatever set of criteria is desired; +3. To carry information about what caused the event, which may be provided to the process. + +Outside of Watchexec, this library is particularly useful if you're building a tool that runs under +it, and want to easily read its events (with `--emit-events-to=json-file` and `--emit-events-to=json-stdin`). ```rust ,no_run use std::io::{stdin, Result}; diff --git a/crates/events/src/lib.rs b/crates/events/src/lib.rs index 5860db5..2705022 100644 --- a/crates/events/src/lib.rs +++ b/crates/events/src/lib.rs @@ -1,10 +1,4 @@ -//! Synthetic event type, derived from inputs, triggers actions. -//! -//! Fundamentally, events in watchexec have three purposes: -//! -//! 1. To trigger the launch, restart, or other interruption of a process; -//! 2. To be filtered upon according to whatever set of criteria is desired; -//! 3. To carry information about what caused the event, which may be provided to the process. +#![doc = include_str!("../README.md")] #[doc(inline)] pub use event::*; diff --git a/crates/ignore-files/src/discover.rs b/crates/ignore-files/src/discover.rs index 6126411..e5bcf22 100644 --- a/crates/ignore-files/src/discover.rs +++ b/crates/ignore-files/src/discover.rs @@ -23,7 +23,7 @@ use crate::{IgnoreFile, IgnoreFilter}; /// /// Importantly, this should be called from the origin of the project, not a subfolder. This /// function will not discover the project origin, and will not traverse parent directories. Use the -/// [`project::origins`](crate::project::origins) function for that. +/// `project-origins` crate for that. /// /// This function also does not distinguish between project folder types, and collects all files for /// all supported VCSs and other project types. Use the `applies_to` field to filter the results. diff --git a/crates/ignore-files/src/error.rs b/crates/ignore-files/src/error.rs index d16b2b2..b96eb98 100644 --- a/crates/ignore-files/src/error.rs +++ b/crates/ignore-files/src/error.rs @@ -33,7 +33,7 @@ pub enum Error { // TODO: extract glob error into diagnostic }, - /// Multiple related [`Error`]s. + /// Multiple related [`Error`](enum@Error)s. #[error("multiple: {0:?}")] #[diagnostic(code(ignore_file::set))] Multi(#[related] Vec), diff --git a/crates/ignore-files/src/filter.rs b/crates/ignore-files/src/filter.rs index 2f3893c..d05f426 100644 --- a/crates/ignore-files/src/filter.rs +++ b/crates/ignore-files/src/filter.rs @@ -14,7 +14,7 @@ use crate::{Error, IgnoreFile}; /// /// This reads and compiles ignore files, and should be used for handling ignore files. It's created /// with a project origin and a list of ignore files, and new ignore files can be added later -/// (unless [`finish`](IgnoreFilterer::finish()) is called). +/// (unless [`finish`](IgnoreFilter::finish()) is called). #[derive(Clone, Debug)] pub struct IgnoreFilter { origin: PathBuf, @@ -25,7 +25,7 @@ pub struct IgnoreFilter { impl IgnoreFilter { /// Create a new empty filterer. /// - /// Prefer [`new()`](IgnoreFilterer::new()) if you have ignore files ready to use. + /// Prefer [`new()`](IgnoreFilter::new()) if you have ignore files ready to use. pub fn empty(origin: impl AsRef) -> Self { let origin = origin.as_ref(); Self { @@ -37,7 +37,7 @@ impl IgnoreFilter { /// Read ignore files from disk and load them for filtering. /// - /// Use [`empty()`](IgnoreFilterer::empty()) if you want an empty filterer, + /// Use [`empty()`](IgnoreFilter::empty()) if you want an empty filterer, /// or to construct one outside an async environment. pub async fn new(origin: impl AsRef + Send, files: &[IgnoreFile]) -> Result { let origin = origin.as_ref(); @@ -219,8 +219,8 @@ impl IgnoreFilter { /// /// Returns `false` if the folder should be ignored. /// - /// Note that this is a slightly different implementation than the [`Filterer`] trait, as the - /// latter handles events with multiple associated paths. + /// Note that this is a slightly different implementation than watchexec's Filterer trait, as + /// the latter handles events with multiple associated paths. pub fn check_dir(&self, path: &Path) -> bool { let _span = trace_span!("check_dir", ?path).entered(); diff --git a/crates/lib/src/error/runtime.rs b/crates/lib/src/error/runtime.rs index 8907401..a13b395 100644 --- a/crates/lib/src/error/runtime.rs +++ b/crates/lib/src/error/runtime.rs @@ -9,6 +9,62 @@ use crate::{ /// Errors which _may_ be recoverable, transient, or only affect a part of the operation, and should /// be reported to the user and/or acted upon programatically, but will not outright stop watchexec. +/// +/// Some errors that are classified here are spurious and may be ignored; in general you should not +/// use the convenience print handlers for handling these errors beyond prototyping. For example, +/// "waiting on process" errors should not be printed to the user by default: +/// +/// ``` +/// # use std::convert::Infallible; +/// # use tracing::error; +/// # use watchexec::{config::InitConfig, ErrorHook, error::RuntimeError, handler::SyncFnHandler}; +/// # let mut config = InitConfig::default(); +/// config.on_error(SyncFnHandler::from( +/// |err: ErrorHook| -> std::result::Result<(), Infallible> { +/// if let RuntimeError::IoError { +/// about: "waiting on process group", +/// .. +/// } = err.error +/// { +/// error!("{}", err.error); +/// return Ok(()); +/// } +/// +/// // ... +/// +/// Ok(()) +/// }, +/// )); +/// ``` +/// +/// On the other hand, some errors may not be fatal to this library's understanding, but will be to +/// your application. In those cases, you should "elevate" these errors, which will transform them +/// to [`CriticalError`](super::CriticalError)s: +/// +/// ``` +/// # use std::convert::Infallible; +/// # use watchexec::{config::InitConfig, ErrorHook, error::{RuntimeError, FsWatcherError}, handler::SyncFnHandler}; +/// # let mut config = InitConfig::default(); +/// config.on_error(SyncFnHandler::from( +/// |err: ErrorHook| -> std::result::Result<(), Infallible> { +/// if let RuntimeError::FsWatcher { +/// err: +/// FsWatcherError::Create { .. } +/// | FsWatcherError::TooManyWatches { .. } +/// | FsWatcherError::TooManyHandles { .. }, +/// .. +/// } = err.error +/// { +/// err.elevate(); +/// return Ok(()); +/// } +/// +/// // ... +/// +/// Ok(()) +/// }, +/// )); +/// ``` #[derive(Debug, Diagnostic, Error)] #[non_exhaustive] #[diagnostic(url(docsrs))] diff --git a/crates/lib/src/lib.rs b/crates/lib/src/lib.rs index ca54af7..8915eff 100644 --- a/crates/lib/src/lib.rs +++ b/crates/lib/src/lib.rs @@ -88,9 +88,6 @@ //! printing even error log messages for this crate unless it's for debugging. Instead, make use of //! the [`InitConfig::on_error()`][config::InitConfig::on_error()] method to define a handler for //! errors occurring at runtime that are _meant_ for you to handle (by printing out or otherwise). -//! -//! This crate does not itself use `unsafe`. However, it depends on a number of libraries which do, -//! most because they interact with the operating system. #![doc(html_favicon_url = "https://watchexec.github.io/logo:watchexec.svg")] #![doc(html_logo_url = "https://watchexec.github.io/logo:watchexec.svg")] diff --git a/crates/signals/README.md b/crates/signals/README.md index 224b5ba..3249975 100644 --- a/crates/signals/README.md +++ b/crates/signals/README.md @@ -10,6 +10,7 @@ _Watchexec's signal type._ [license]: ../../LICENSE ```rust +use std::str::FromStr; use watchexec_signals::Signal; fn main() { diff --git a/crates/signals/src/lib.rs b/crates/signals/src/lib.rs index ac37d0f..969ec49 100644 --- a/crates/signals/src/lib.rs +++ b/crates/signals/src/lib.rs @@ -1,15 +1,4 @@ -//! Notifications (signals or Windows control events) sent to a process. -//! -//! This signal type in Watchexec is used for any of: -//! - signals sent to the main process by some external actor, -//! - signals received from a sub process by the main process, -//! - signals sent to a sub process by Watchexec. -//! -//! ## Features -//! -//! - `fromstr`: Enables parsing of signals from strings. -//! - `serde`: Enables [`serde`][serde] support. Note that this is stricter than string parsing. -//! - `miette`: Enables [`miette`][miette] support for [`SignalParseError`][SignalParseError]. +#![doc = include_str!("../README.md")] use std::fmt; @@ -19,7 +8,12 @@ use std::str::FromStr; #[cfg(unix)] use nix::sys::signal::Signal as NixSignal; -/// A notification sent to a process. +/// A notification (signals or Windows control events) sent to a process. +/// +/// This signal type in Watchexec is used for any of: +/// - signals sent to the main process by some external actor, +/// - signals received from a sub process by the main process, +/// - signals sent to a sub process by Watchexec. /// /// On Windows, only some signals are supported, as described. Others will be ignored. /// diff --git a/doc/watchexec.1 b/doc/watchexec.1 index 434c28d..afb8be2 100644 --- a/doc/watchexec.1 +++ b/doc/watchexec.1 @@ -10,7 +10,7 @@ Execute commands when watched files change. .PP Recursively monitors the current directory for changes, executing the command when a filesystem change is detected (among other event sources). By default, watchexec uses efficient kernel\-level mechanisms to watch for changes. .PP -At startup, the specified is run once, and watchexec begins monitoring for changes. +At startup, the specified command is run once, and watchexec begins monitoring for changes. .PP Examples: .PP diff --git a/doc/watchexec.1.md b/doc/watchexec.1.md index 9b4a3bd..bb7b0b3 100644 --- a/doc/watchexec.1.md +++ b/doc/watchexec.1.md @@ -30,7 +30,7 @@ command when a filesystem change is detected (among other event sources). By default, watchexec uses efficient kernel-level mechanisms to watch for changes. -At startup, the specified \ is run once, and watchexec begins +At startup, the specified command is run once, and watchexec begins monitoring for changes. Examples: diff --git a/doc/watchexec.1.pdf b/doc/watchexec.1.pdf index e3121a2eb2827aca6b3948e8b055940075072343..413afad3b9e8ecd3abe89fe7ca229ee795043ef9 100644 GIT binary patch delta 2989 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