crates/cli/src/escape.rs

@@ -8,7 +8,7 @@ use bstr::{ByteSlice, ByteVec}; /// converts the non-printable subset of ASCII in addition to invalid UTF-8 /// bytes to hexadecimal escape sequences. Everything else is left as is. ///-/// The dual of this routine is [`unescape`](fn.unescape.html).+/// The dual of this routine is [`unescape`]. /// /// # Example ///@@ -29,7 +29,7 @@ pub fn escape(bytes: &[u8]) -> String {  /// Escapes an OS string into a human readable string. ///-/// This is like [`escape`](fn.escape.html), but accepts an OS string.+/// This is like [`escape`], but accepts an OS string. pub fn escape_os(string: &OsStr) -> String {     escape(Vec::from_os_str_lossy(string).as_bytes()) }@@ -48,7 +48,7 @@ pub fn escape_os(string: &OsStr) -> String { /// capable of specifying arbitrary bytes or otherwise make it easier to /// specify non-printable characters. ///-/// The dual of this routine is [`escape`](fn.escape.html).+/// The dual of this routine is [`escape`]. /// /// # Example ///@@ -70,7 +70,7 @@ pub fn unescape(s: &str) -> Vec<u8> {  /// Unescapes an OS string. ///-/// This is like [`unescape`](fn.unescape.html), but accepts an OS string.+/// This is like [`unescape`], but accepts an OS string. /// /// Note that this first lossily decodes the given OS string as UTF-8. That /// is, an escaped string (the thing given) should be valid UTF-8.

crates/cli/src/lib.rs

@@ -20,22 +20,17 @@ recursively search the current working directory for occurrences of `foo`, but  # Coloring and buffering -The-[`stdout`](fn.stdout.html),-[`stdout_buffered_block`](fn.stdout_buffered_block.html)-and-[`stdout_buffered_line`](fn.stdout_buffered_line.html)-routines are alternative constructors for-[`StandardStream`](struct.StandardStream.html).-A `StandardStream` implements `termcolor::WriteColor`, which provides a way-to emit colors to terminals. Its key use is the encapsulation of buffering-style. Namely, `stdout` will return a line buffered `StandardStream` if and-only if stdout is connected to a tty, and will otherwise return a block-buffered `StandardStream`. Line buffering is important for use with a tty-because it typically decreases the latency at which the end user sees output.-Block buffering is used otherwise because it is faster, and redirecting stdout-to a file typically doesn't benefit from the decreased latency that line-buffering provides.+The [`stdout`], [`stdout_buffered_block`] and [`stdout_buffered_line`] routines+are alternative constructors for [`StandardStream`]. A `StandardStream`+implements `termcolor::WriteColor`, which provides a way to emit colors to+terminals. Its key use is the encapsulation of buffering style. Namely,+`stdout` will return a line buffered `StandardStream` if and only if+stdout is connected to a tty, and will otherwise return a block buffered+`StandardStream`. Line buffering is important for use with a tty because it+typically decreases the latency at which the end user sees output. Block+buffering is used otherwise because it is faster, and redirecting stdout to a+file typically doesn't benefit from the decreased latency that line buffering+provides.  The `stdout_buffered_block` and `stdout_buffered_line` can be used to explicitly set the buffering strategy regardless of whether stdout is connected@@ -44,17 +39,12 @@ to a tty or not.  # Escaping -The-[`escape`](fn.escape.html),-[`escape_os`](fn.escape_os.html),-[`unescape`](fn.unescape.html)-and-[`unescape_os`](fn.unescape_os.html)-routines provide a user friendly way of dealing with UTF-8 encoded strings that-can express arbitrary bytes. For example, you might want to accept a string-containing arbitrary bytes as a command line argument, but most interactive-shells make such strings difficult to type. Instead, we can ask users to use-escape sequences.+The [`escape`](crate::escape()), [`escape_os`], [`unescape`] and+[`unescape_os`] routines provide a user friendly way of dealing with UTF-8+encoded strings that can express arbitrary bytes. For example, you might want+to accept a string containing arbitrary bytes as a command line argument, but+most interactive shells make such strings difficult to type. Instead, we can+ask users to use escape sequences.  For example, `a\xFFz` is itself a valid UTF-8 string corresponding to the following bytes:@@ -87,44 +77,36 @@ makes it easy to show user friendly error messages involving arbitrary bytes. # Building patterns  Typically, regular expression patterns must be valid UTF-8. However, command-line arguments aren't guaranteed to be valid UTF-8. Unfortunately, the-standard library's UTF-8 conversion functions from `OsStr`s do not provide-good error messages. However, the-[`pattern_from_bytes`](fn.pattern_from_bytes.html)-and-[`pattern_from_os`](fn.pattern_from_os.html)-do, including reporting exactly where the first invalid UTF-8 byte is seen.+line arguments aren't guaranteed to be valid UTF-8. Unfortunately, the standard+library's UTF-8 conversion functions from `OsStr`s do not provide good error+messages. However, the [`pattern_from_bytes`] and [`pattern_from_os`] do,+including reporting exactly where the first invalid UTF-8 byte is seen.  Additionally, it can be useful to read patterns from a file while reporting-good error messages that include line numbers. The-[`patterns_from_path`](fn.patterns_from_path.html),-[`patterns_from_reader`](fn.patterns_from_reader.html)-and-[`patterns_from_stdin`](fn.patterns_from_stdin.html)-routines do just that. If any pattern is found that is invalid UTF-8, then the-error includes the file path (if available) along with the line number and the-byte offset at which the first invalid UTF-8 byte was observed.+good error messages that include line numbers. The [`patterns_from_path`],+[`patterns_from_reader`] and [`patterns_from_stdin`] routines do just that. If+any pattern is found that is invalid UTF-8, then the error includes the file+path (if available) along with the line number and the byte offset at which the+first invalid UTF-8 byte was observed.   # Read process output -Sometimes a command line application needs to execute other processes and read-its stdout in a streaming fashion. The-[`CommandReader`](struct.CommandReader.html)-provides this functionality with an explicit goal of improving failure modes.-In particular, if the process exits with an error code, then stderr is read-and converted into a normal Rust error to show to end users. This makes the-underlying failure modes explicit and gives more information to end users for-debugging the problem.--As a special case,-[`DecompressionReader`](struct.DecompressionReader.html)-provides a way to decompress arbitrary files by matching their file extensions-up with corresponding decompression programs (such as `gzip` and `xz`). This-is useful as a means of performing simplistic decompression in a portable-manner without binding to specific compression libraries. This does come with-some overhead though, so if you need to decompress lots of small files, this-may not be an appropriate convenience to use.+Sometimes a command line application needs to execute other processes and+read its stdout in a streaming fashion. The [`CommandReader`] provides this+functionality with an explicit goal of improving failure modes. In particular,+if the process exits with an error code, then stderr is read and converted into+a normal Rust error to show to end users. This makes the underlying failure+modes explicit and gives more information to end users for debugging the+problem.++As a special case, [`DecompressionReader`] provides a way to decompress+arbitrary files by matching their file extensions up with corresponding+decompression programs (such as `gzip` and `xz`). This is useful as a means of+performing simplistic decompression in a portable manner without binding to+specific compression libraries. This does come with some overhead though, so+if you need to decompress lots of small files, this may not be an appropriate+convenience to use.  Each reader has a corresponding builder for additional configuration, such as whether to read stderr asynchronously in order to avoid deadlock (which is@@ -133,11 +115,10 @@ enabled by default).  # Miscellaneous parsing -The-[`parse_human_readable_size`](fn.parse_human_readable_size.html)-routine parses strings like `2M` and converts them to the corresponding number-of bytes (`2 * 1<<20` in this case). If an invalid size is found, then a good-error message is crafted that typically tells the user how to fix the problem.+The [`parse_human_readable_size`] routine parses strings like `2M` and converts+them to the corresponding number of bytes (`2 * 1<<20` in this case). If an+invalid size is found, then a good error message is crafted that typically+tells the user how to fix the problem. */  #![deny(missing_docs)]

crates/cli/src/process.rs

@@ -191,8 +191,7 @@ impl CommandReader {     /// returned.     ///     /// If the caller requires additional configuration for the reader-    /// returned, then use-    /// [`CommandReaderBuilder`](struct.CommandReaderBuilder.html).+    /// returned, then use [`CommandReaderBuilder`].     pub fn new(         cmd: &mut process::Command,     ) -> Result<CommandReader, CommandError> {

crates/cli/src/wtr.rs

@@ -33,10 +33,8 @@ pub fn stdout(color_choice: termcolor::ColorChoice) -> StandardStream { /// users see output as soon as it's written. The downside of this approach /// is that it can be slower, especially when there is a lot of output. ///-/// You might consider using-/// [`stdout`](fn.stdout.html)-/// instead, which chooses the buffering strategy automatically based on-/// whether stdout is connected to a tty.+/// You might consider using [`stdout`] instead, which chooses the buffering+/// strategy automatically based on whether stdout is connected to a tty. pub fn stdout_buffered_line(     color_choice: termcolor::ColorChoice, ) -> StandardStream {@@ -50,10 +48,8 @@ pub fn stdout_buffered_line( /// the cost of writing data. The downside of this approach is that it can /// increase the latency of display output when writing to a tty. ///-/// You might consider using-/// [`stdout`](fn.stdout.html)-/// instead, which chooses the buffering strategy automatically based on-/// whether stdout is connected to a tty.+/// You might consider using [`stdout`] instead, which chooses the buffering+/// strategy automatically based on whether stdout is connected to a tty. pub fn stdout_buffered_block(     color_choice: termcolor::ColorChoice, ) -> StandardStream {

crates/ignore/src/walk.rs

@@ -38,9 +38,7 @@ impl DirEntry {     }      /// The full path that this entry represents.-    /// Analogous to [`path`], but moves ownership of the path.-    ///-    /// [`path`]: struct.DirEntry.html#method.path+    /// Analogous to [`DirEntry::path`], but moves ownership of the path.     pub fn into_path(self) -> PathBuf {         self.dent.into_path()     }@@ -1127,10 +1125,10 @@ impl WalkState {     } } -/// A builder for constructing a visitor when using-/// [`WalkParallel::visit`](struct.WalkParallel.html#method.visit). The builder-/// will be called for each thread started by `WalkParallel`. The visitor-/// returned from each builder is then called for every directory entry.+/// A builder for constructing a visitor when using [`WalkParallel::visit`].+/// The builder will be called for each thread started by `WalkParallel`. The+/// visitor returned from each builder is then called for every directory+/// entry. pub trait ParallelVisitorBuilder<'s> {     /// Create per-thread `ParallelVisitor`s for `WalkParallel`.     fn build(&mut self) -> Box<dyn ParallelVisitor + 's>;@@ -1147,9 +1145,8 @@ impl<'a, 's, P: ParallelVisitorBuilder<'s>> ParallelVisitorBuilder<'s> /// Receives files and directories for the current thread. /// /// Setup for the traversal can be implemented as part of-/// [`ParallelVisitorBuilder::build`](trait.ParallelVisitorBuilder.html#tymethod.build).-/// Teardown when traversal finishes can be implemented by implementing the-/// `Drop` trait on your traversal type.+/// [`ParallelVisitorBuilder::build`]. Teardown when traversal finishes can be+/// implemented by implementing the `Drop` trait on your traversal type. pub trait ParallelVisitor: Send {     /// Receives files and directories for the current thread. This is called     /// once for every directory entry visited by traversal.

crates/matcher/src/lib.rs

@@ -6,12 +6,10 @@ the search routines provided by the [`grep-searcher`](https://docs.rs/grep-searcher) crate. -The primary thing provided by this crate is the-[`Matcher`](trait.Matcher.html)-trait. The trait defines an abstract interface for text search. It is robust-enough to support everything from basic substring search all the way to-arbitrarily complex regular expression implementations without sacrificing-performance.+The primary thing provided by this crate is the [`Matcher`] trait. The trait+defines an abstract interface for text search. It is robust enough to support+everything from basic substring search all the way to arbitrarily complex+regular expression implementations without sacrificing performance.  A key design decision made in this crate is the use of *internal iteration*, or otherwise known as the "push" model of searching. In this paradigm,@@ -513,13 +511,11 @@ pub enum LineMatchKind { /// A matcher defines an interface for regular expression implementations. /// /// While this trait is large, there are only two required methods that-/// implementors must provide: `find_at` and `new_captures`. If captures-/// aren't supported by your implementation, then `new_captures` can be-/// implemented with-/// [`NoCaptures`](struct.NoCaptures.html). If your implementation does support-/// capture groups, then you should also implement the other capture related-/// methods, as dictated by the documentation. Crucially, this includes-/// `captures_at`.+/// implementors must provide: `find_at` and `new_captures`. If captures aren't+/// supported by your implementation, then `new_captures` can be implemented+/// with [`NoCaptures`]. If your implementation does support capture groups,+/// then you should also implement the other capture related methods, as+/// dictated by the documentation. Crucially, this includes `captures_at`. /// /// The rest of the methods on this trait provide default implementations on /// top of `find_at` and `new_captures`. It is not uncommon for implementations

crates/printer/src/color.rs

@@ -83,7 +83,7 @@ impl std::fmt::Display for ColorError { /// This set of color specifications represents the various color types that /// are supported by the printers in this crate. A set of color specifications /// can be created from a sequence of-/// [`UserColorSpec`s](struct.UserColorSpec.html).+/// [`UserColorSpec`]s. #[derive(Clone, Debug, Default, Eq, PartialEq)] pub struct ColorSpecs {     path: ColorSpec,

crates/printer/src/json.rs

@@ -549,14 +549,13 @@ impl<W> JSON<W> { /// This type is generic over a few type parameters: /// /// * `'p` refers to the lifetime of the file path, if one is provided. When-///   no file path is given, then this is `'static`.-/// * `'s` refers to the lifetime of the-///   [`JSON`](struct.JSON.html)-///   printer that this type borrows.+/// no file path is given, then this is `'static`.+/// * `'s` refers to the lifetime of the [`JSON`] printer that this type+/// borrows. /// * `M` refers to the type of matcher used by-///   `grep_searcher::Searcher` that is reporting results to this sink.+/// `grep_searcher::Searcher` that is reporting results to this sink. /// * `W` refers to the underlying writer that this printer is writing its-///   output to.+/// output to. #[derive(Debug)] pub struct JSONSink<'p, 's, M: Matcher, W> {     matcher: M,

crates/printer/src/lib.rs

@@ -5,22 +5,20 @@ crate.  # Brief overview -The [`Standard`](struct.Standard.html) printer shows results in a human-readable format, and is modeled after the formats used by standard grep-like-tools. Features include, but are not limited to, cross platform terminal-coloring, search & replace, multi-line result handling and reporting summary-statistics.--The [`JSON`](struct.JSON.html) printer shows results in a machine readable-format. To facilitate a stream of search results, the format uses-[JSON Lines](https://jsonlines.org/)-by emitting a series of messages as search results are found.--The [`Summary`](struct.Summary.html) printer shows *aggregate* results for a-single search in a human readable format, and is modeled after similar formats-found in standard grep-like tools. This printer is useful for showing the total-number of matches and/or printing file paths that either contain or don't-contain matches.+The [`Standard`] printer shows results in a human readable format, and is+modeled after the formats used by standard grep-like tools. Features include,+but are not limited to, cross platform terminal coloring, search & replace,+multi-line result handling and reporting summary statistics.++The [`JSON`] printer shows results in a machine readable format.+To facilitate a stream of search results, the format uses [JSON+Lines](https://jsonlines.org/) by emitting a series of messages as search+results are found.++The [`Summary`] printer shows *aggregate* results for a single search in a+human readable format, and is modeled after similar formats found in standard+grep-like tools. This printer is useful for showing the total number of matches+and/or printing file paths that either contain or don't contain matches.  # Example 

crates/printer/src/standard.rs

@@ -149,11 +149,11 @@ impl StandardBuilder {      /// Set the user color specifications to use for coloring in this printer.     ///-    /// A [`UserColorSpec`](struct.UserColorSpec.html) can be constructed from-    /// a string in accordance with the color specification format. See the-    /// `UserColorSpec` type documentation for more details on the format.-    /// A [`ColorSpecs`](struct.ColorSpecs.html) can then be generated from-    /// zero or more `UserColorSpec`s.+    /// A [`UserColorSpec`](crate::UserColorSpec) can be constructed from+    /// a string in accordance with the color specification format. See+    /// the `UserColorSpec` type documentation for more details on the+    /// format. A [`ColorSpecs`] can then be generated from zero or more+    /// `UserColorSpec`s.     ///     /// Regardless of the color specifications provided here, whether color     /// is actually used or not is determined by the implementation of@@ -196,15 +196,13 @@ impl StandardBuilder {     /// number of bytes searched and the total number of bytes printed.     ///     /// Aggregate statistics can be accessed via the sink's-    /// [`StandardSink::stats`](struct.StandardSink.html#method.stats)-    /// method.+    /// [`StandardSink::stats`] method.     ///     /// When this is enabled, this printer may need to do extra work in order     /// to compute certain statistics, which could cause the search to take     /// longer.     ///-    /// For a complete description of available statistics, see-    /// [`Stats`](struct.Stats.html).+    /// For a complete description of available statistics, see [`Stats`].     pub fn stats(&mut self, yes: bool) -> &mut StandardBuilder {         self.config.stats = yes;         self@@ -484,7 +482,7 @@ impl StandardBuilder { /// A default printer can be created with either of the `Standard::new` or /// `Standard::new_no_color` constructors. However, there are a considerable /// number of options that configure this printer's output. Those options can-/// be configured using [`StandardBuilder`](struct.StandardBuilder.html).+/// be configured using [`StandardBuilder`]. /// /// This type is generic over `W`, which represents any implementation /// of the `termcolor::WriteColor` trait. If colors are not desired,@@ -633,12 +631,9 @@ impl<W> Standard<W> { /// An implementation of `Sink` associated with a matcher and an optional file /// path for the standard printer. ///-/// A `Sink` can be created via the-/// [`Standard::sink`](struct.Standard.html#method.sink)-/// or-/// [`Standard::sink_with_path`](struct.Standard.html#method.sink_with_path)-/// methods, depending on whether you want to include a file path in the-/// printer's output.+/// A `Sink` can be created via the [`Standard::sink`] or+/// [`Standard::sink_with_path`] methods, depending on whether you want to+/// include a file path in the printer's output. /// /// Building a `StandardSink` is cheap, and callers should create a new one /// for each thing that is searched. After a search has completed, callers may@@ -648,14 +643,13 @@ impl<W> Standard<W> { /// This type is generic over a few type parameters: /// /// * `'p` refers to the lifetime of the file path, if one is provided. When-///   no file path is given, then this is `'static`.-/// * `'s` refers to the lifetime of the-///   [`Standard`](struct.Standard.html)-///   printer that this type borrows.+/// no file path is given, then this is `'static`.+/// * `'s` refers to the lifetime of the [`Standard`] printer that this type+/// borrows. /// * `M` refers to the type of matcher used by-///   `grep_searcher::Searcher` that is reporting results to this sink.+/// `grep_searcher::Searcher` that is reporting results to this sink. /// * `W` refers to the underlying writer that this printer is writing its-///   output to.+/// output to. #[derive(Debug)] pub struct StandardSink<'p, 's, M: Matcher, W> {     matcher: M,@@ -710,8 +704,7 @@ impl<'p, 's, M: Matcher, W: WriteColor> StandardSink<'p, 's, M, W> {     /// searches executed on this sink.     ///     /// This only returns stats if they were requested via the-    /// [`StandardBuilder`](struct.StandardBuilder.html)-    /// configuration.+    /// [`StandardBuilder`] configuration.     pub fn stats(&self) -> Option<&Stats> {         self.stats.as_ref()     }

crates/printer/src/summary.rs

@@ -193,11 +193,11 @@ impl SummaryBuilder {      /// Set the user color specifications to use for coloring in this printer.     ///-    /// A [`UserColorSpec`](struct.UserColorSpec.html) can be constructed from-    /// a string in accordance with the color specification format. See the-    /// `UserColorSpec` type documentation for more details on the format.-    /// A [`ColorSpecs`](struct.ColorSpecs.html) can then be generated from-    /// zero or more `UserColorSpec`s.+    /// A [`UserColorSpec`](crate::UserColorSpec) can be constructed from+    /// a string in accordance with the color specification format. See+    /// the `UserColorSpec` type documentation for more details on the+    /// format. A [`ColorSpecs`] can then be generated from zero or more+    /// `UserColorSpec`s.     ///     /// Regardless of the color specifications provided here, whether color     /// is actually used or not is determined by the implementation of@@ -242,8 +242,7 @@ impl SummaryBuilder {     /// number of bytes searched and the total number of bytes printed.     ///     /// Aggregate statistics can be accessed via the sink's-    /// [`SummarySink::stats`](struct.SummarySink.html#method.stats)-    /// method.+    /// [`SummarySink::stats`] method.     ///     /// When this is enabled, this printer may need to do extra work in order     /// to compute certain statistics, which could cause the search to take@@ -251,8 +250,7 @@ impl SummaryBuilder {     /// the first match, but if `stats` is enabled, then the search will     /// continue after the first match in order to compute statistics.     ///-    /// For a complete description of available statistics, see-    /// [`Stats`](struct.Stats.html).+    /// For a complete description of available statistics, see [`Stats`].     ///     /// Note that some output modes, such as `CountMatches`, automatically     /// enable this option even if it has been explicitly disabled.@@ -348,7 +346,7 @@ impl SummaryBuilder { /// A default printer can be created with either of the `Summary::new` or /// `Summary::new_no_color` constructors. However, there are a number of /// options that configure this printer's output. Those options can be-/// configured using [`SummaryBuilder`](struct.SummaryBuilder.html).+/// configured using [`SummaryBuilder`]. /// /// This type is generic over `W`, which represents any implementation of /// the `termcolor::WriteColor` trait.@@ -480,14 +478,13 @@ impl<W> Summary<W> { /// This type is generic over a few type parameters: /// /// * `'p` refers to the lifetime of the file path, if one is provided. When-///   no file path is given, then this is `'static`.-/// * `'s` refers to the lifetime of the-///   [`Summary`](struct.Summary.html)-///   printer that this type borrows.+/// no file path is given, then this is `'static`.+/// * `'s` refers to the lifetime of the [`Summary`] printer that this type+/// borrows. /// * `M` refers to the type of matcher used by-///   `grep_searcher::Searcher` that is reporting results to this sink.+/// `grep_searcher::Searcher` that is reporting results to this sink. /// * `W` refers to the underlying writer that this printer is writing its-///   output to.+/// output to. #[derive(Debug)] pub struct SummarySink<'p, 's, M: Matcher, W> {     matcher: M,@@ -531,8 +528,7 @@ impl<'p, 's, M: Matcher, W: WriteColor> SummarySink<'p, 's, M, W> {     /// searches executed on this sink.     ///     /// This only returns stats if they were requested via the-    /// [`SummaryBuilder`](struct.SummaryBuilder.html)-    /// configuration.+    /// [`SummaryBuilder`] configuration.     pub fn stats(&self) -> Option<&Stats> {         self.stats.as_ref()     }

crates/searcher/src/lib.rs

@@ -4,48 +4,38 @@ support for multi-line search.  # Brief overview -The principle type in this crate is a-[`Searcher`](struct.Searcher.html),-which can be configured and built by a-[`SearcherBuilder`](struct.SearcherBuilder.html).-A `Searcher` is responsible for reading bytes from a source (e.g., a file),-executing a search of those bytes using a `Matcher` (e.g., a regex) and then-reporting the results of that search to a-[`Sink`](trait.Sink.html)-(e.g., stdout). The `Searcher` itself is principally responsible for managing-the consumption of bytes from a source and applying a `Matcher` over those-bytes in an efficient way. The `Searcher` is also responsible for inverting-a search, counting lines, reporting contextual lines, detecting binary data-and even deciding whether or not to use memory maps.+The principle type in this crate is a [`Searcher`], which can be configured+and built by a [`SearcherBuilder`]. A `Searcher` is responsible for reading+bytes from a source (e.g., a file), executing a search of those bytes using+a `Matcher` (e.g., a regex) and then reporting the results of that search to+a [`Sink`] (e.g., stdout). The `Searcher` itself is principally responsible+for managing the consumption of bytes from a source and applying a `Matcher`+over those bytes in an efficient way. The `Searcher` is also responsible for+inverting a search, counting lines, reporting contextual lines, detecting+binary data and even deciding whether or not to use memory maps.  A `Matcher` (which is defined in the-[`grep-matcher`](https://crates.io/crates/grep-matcher)-crate) is a trait for describing the lowest levels of pattern search in a-generic way. The interface itself is very similar to the interface of a regular-expression. For example, the-[`grep-regex`](https://crates.io/crates/grep-regex)+[`grep-matcher`](https://crates.io/crates/grep-matcher) crate) is a trait+for describing the lowest levels of pattern search in a generic way. The+interface itself is very similar to the interface of a regular expression.+For example, the [`grep-regex`](https://crates.io/crates/grep-regex) crate provides an implementation of the `Matcher` trait using Rust's-[`regex`](https://crates.io/crates/regex)-crate.+[`regex`](https://crates.io/crates/regex) crate.  Finally, a `Sink` describes how callers receive search results producer by a `Searcher`. This includes routines that are called at the beginning and end of a search, in addition to routines that are called when matching or contextual lines are found by the `Searcher`. Implementations of `Sink` can be trivially-simple, or extraordinarily complex, such as the-`Standard` printer found in the-[`grep-printer`](https://crates.io/crates/grep-printer)-crate, which effectively implements grep-like output.-This crate also provides convenience `Sink` implementations in the-[`sinks`](sinks/index.html)-sub-module for easy searching with closures.+simple, or extraordinarily complex, such as the `Standard` printer found in+the [`grep-printer`](https://crates.io/crates/grep-printer) crate, which+effectively implements grep-like output. This crate also provides convenience+`Sink` implementations in the [`sinks`] sub-module for easy searching with+closures.  # Example  This example shows how to execute the searcher and read the search results-using the-[`UTF8`](sinks/struct.UTF8.html)-implementation of `Sink`.+using the [`UTF8`](sinks::UTF8) implementation of `Sink`.  ``` use std::error::Error;

crates/searcher/src/searcher/mod.rs

@@ -114,9 +114,8 @@ impl BinaryDetection {  /// An encoding to use when searching. ///-/// An encoding can be used to configure a-/// [`SearcherBuilder`](struct.SearchBuilder.html)-/// to transcode source data from an encoding to UTF-8 before searching.+/// An encoding can be used to configure a [`SearcherBuilder`] to transcode+/// source data from an encoding to UTF-8 before searching. /// /// An `Encoding` will always be cheap to clone. #[derive(Clone, Debug)]@@ -508,8 +507,7 @@ impl SearcherBuilder {     ///     /// The binary detection strategy determines not only how the searcher     /// detects binary data, but how it responds to the presence of binary-    /// data. See the [`BinaryDetection`](struct.BinaryDetection.html) type-    /// for more information.+    /// data. See the [`BinaryDetection`] type for more information.     ///     /// By default, binary detection is disabled.     pub fn binary_detection(@@ -616,8 +614,7 @@ impl Searcher {     /// Create a new searcher with a default configuration.     ///     /// To configure the searcher (e.g., invert matching, enable memory maps,-    /// enable contexts, etc.), use the-    /// [`SearcherBuilder`](struct.SearcherBuilder.html).+    /// enable contexts, etc.), use the [`SearcherBuilder`].     pub fn new() -> Searcher {         SearcherBuilder::new().build()     }@@ -817,9 +814,8 @@ impl Searcher { }  /// The following methods permit querying the configuration of a searcher.-/// These can be useful in generic implementations of-/// [`Sink`](trait.Sink.html),-/// where the output may be tailored based on how the searcher is configured.+/// These can be useful in generic implementations of [`Sink`], where the+/// output may be tailored based on how the searcher is configured. impl Searcher {     /// Returns the line terminator used by this searcher.     #[inline]

crates/searcher/src/sink.rs

@@ -74,8 +74,8 @@ impl SinkError for Box<dyn error::Error> { /// /// * What to do when a match is found. Callers must provide this. /// * What to do when an error occurs. Callers must provide this via the-///   [`SinkError`](trait.SinkError.html) trait. Generally, callers can just-///   use `io::Error` for this, which already implements `SinkError`.+///   [`SinkError`] trait. Generally, callers can just use `io::Error` for+///   this, which already implements `SinkError`. /// * What to do when a contextual line is found. By default, these are ///   ignored. /// * What to do when a gap between contextual lines has been found. By@@ -95,7 +95,7 @@ impl SinkError for Box<dyn error::Error> { /// /// For simpler uses of `Sink`, callers may elect to use one of /// the more convenient but less flexible implementations in the-/// [`sinks`](sinks/index.html) module.+/// [`sinks`] module. pub trait Sink {     /// The type of an error that should be reported by a searcher.     ///