Fix and adjust docs (#530)

.gitattributes

@@ -1 +1,3 @@
 Cargo.lock merge=binary
+doc/watchexec.* merge=binary
+completions/* merge=binary

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 <COMMAND> is run once, and watchexec begins monitoring for changes.
+/// At startup, the specified command is run once, and watchexec begins monitoring for changes.
 ///
 /// Examples:
 ///

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};

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::*;

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.

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<Error>),

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<Path>) -> 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<Path> + Send, files: &[IgnoreFile]) -> Result<Self, Error> {
 		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();
 

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))]

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")]

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() {

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.
 ///

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 <COMMAND> 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

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 \<COMMAND\> is run once, and watchexec begins
+At startup, the specified command is run once, and watchexec begins
 monitoring for changes.
 
 Examples: