doc: minor touchups to API docs

grep-printer/src/standard.rs

@@ -239,8 +239,9 @@ impl StandardBuilder {
     /// which may either be in index form (e.g., `$2`) or can reference named
     /// capturing groups if present in the original pattern (e.g., `$foo`).
     ///
-    /// For documentation on the full format, please see the `Matcher` trait's
+    /// For documentation on the full format, please see the `Capture` trait's
-    /// `interpolate` method.
+    /// `interpolate` method in the
+    /// [grep-printer](https://docs.rs/grep-printer) crate.
     pub fn replacement(
         &mut self,
         replacement: Option<Vec<u8>>,

grep-regex/src/matcher.rs

@@ -323,8 +323,15 @@ impl RegexMatcher {
     /// Create a new matcher from the given pattern using the default
     /// configuration, but matches lines terminated by `\n`.
     ///
-    /// This returns an error if the given pattern contains a literal `\n`.
+    /// This is meant to be a convenience constructor for using a
-    /// Other uses of `\n` (such as in `\s`) are removed transparently.
+    /// `RegexMatcherBuilder` and setting its
+    /// [`line_terminator`](struct.RegexMatcherBuilder.html#method.line_terminator)
+    /// to `\n`. The purpose of using this constructor is to permit special
+    /// optimizations that help speed up line oriented search. These types of
+    /// optimizations are only appropriate when matches span no more than one
+    /// line. For this reason, this constructor will return an error if the
+    /// given pattern contains a literal `\n`. Other uses of `\n` (such as in
+    /// `\s`) are removed transparently.
     pub fn new_line_matcher(pattern: &str) -> Result<RegexMatcher, Error> {
         RegexMatcherBuilder::new()
             .line_terminator(Some(b'\n'))