implement the parallel doc macro (#635)

src/doc_macros.rs

@@ -17,3 +17,21 @@ macro_rules! generate_mut_doc_comment {
         )
     };
 }
+
+/// A macro for generating the doc-comments for parallel versions of various
+/// image processing functions. It takes the name of the non-parallel function as an
+/// argument as a string literal.
+///
+/// It uses concat! to generate doc-links to the provided original function name
+/// in string literal form.
+macro_rules! generate_parallel_doc_comment {
+    ($name:literal) => {
+        concat!(
+            "An parallel version of [`",
+            $name,
+            "()`].\n\nThis function does the same operation as [`",
+            $name,
+            "()`] but using multi-threading via [`rayon`](https://docs.rs/rayon) iterators.\nRead the top-level crate documentation on parallelism for some of the tradeoffs involved with multi-threaded vs single-threaded image processing functions."
+        )
+    };
+}

src/template_matching.rs

@@ -92,18 +92,7 @@ pub fn match_template(
 }
 
 #[cfg(feature = "rayon")]
-/// Slides a `template` over an `image` and scores the match at each point using
-/// the requested `method`. This version uses rayon to parallelize the computation.
-///
-/// The returned image has dimensions `image.width() - template.width() + 1` by
-/// `image.height() - template.height() + 1`.
-///
-/// See [`MatchTemplateMethod`] for details of the matching methods.
-///
-/// # Panics
-///
-/// If either dimension of `template` is not strictly less than the corresponding dimension
-/// of `image`.
+#[doc = generate_parallel_doc_comment!("match_template")]
 pub fn match_template_parallel(
     image: &GrayImage,
     template: &GrayImage,
@@ -151,18 +140,7 @@ pub fn match_template_with_mask(
 }
 
 #[cfg(feature = "rayon")]
-/// Slides a `template` and a `mask` over an `image` and scores the match at each point using
-/// the requested `method`. This version uses rayon to parallelize the computation.
-///
-/// The returned image has dimensions `image.width() - template.width() + 1` by
-/// `image.height() - template.height() + 1`.
-///
-/// See [`MatchTemplateMethod`] for details of the matching methods.
-///
-/// # Panics
-/// - If either dimension of `template` is not strictly less than the corresponding dimension
-/// of `image`.
-/// - If `template.dimensions() != mask.dimensions()`.
+#[doc = generate_parallel_doc_comment!("match_template_with_mask")]
 pub fn match_template_with_mask_parallel(
     image: &GrayImage,
     template: &GrayImage,