Add docstrings to matcher-combinators.test declarations

CHANGELOG.md

@@ -3,6 +3,9 @@ All notable changes to this project will be documented in this file. This
 change log follows the conventions of
 [keepachangelog.com](http://keepachangelog.com/).
 
+## 3.10.1 / 2026-04-13
+Add docstrings to matcher-combinators.test declarations, used with clojure.test
+
 ## 3.10.0 / 2026-01-27
 - Don't error on mismatches when `actual` value is a Datomic EntityMap.
 - include reporting functions in standalone match result

README.md

@@ -41,7 +41,7 @@ This library addresses this issue by providing composable matcher combinators th
 Require the `matcher-combinators.test` namespace, which will extend `clojure.test`'s `is` macro to accept the `match?` and `thrown-match?` directives.
 
  - `match?`: The first argument should be the matcher-combinator representing the expected value, and the second argument should be the expression being checked.
- - `thrown-match?`: The first argument should be a throwable subclass, the second a matcher-combinator, and the third the expression being checked.
+ - `thrown-match?`: The first argument should be a throwable subclass, the second a matcher-combinator to be applied to the ex-data of the exception thrown, and the third the expression being checked. There is also a 2-arity version that takes just the matcher-combinator and expression.
 
 For example:
 

src/clj/matcher_combinators/clj_test.clj

@@ -156,8 +156,9 @@
   (binding [*out* out]
     (printer/pretty-print (::result/value match-result))))
 
-(defn ^:deprecated build-match-assert
-  "DEPRECATED: use (match? (matchers/match-with <overrides> <expected>) <actual>) "
+(defn build-match-assert
+  {:deprecated "3.0.0"
+   :doc "DEPRECATED: use (match? (matchers/match-with <overrides> <expected>) <actual>)"}
   ([match-assert-name type->matcher msg form]
    (build-match-assert match-assert-name type->matcher msg form
                        (str "DEPRECATION NOTICE: custom assertions for matcher-combinators are deprecated.\n"

src/clj/matcher_combinators/midje.clj

@@ -1,5 +1,5 @@
 (ns matcher-combinators.midje
-  {:deprecated true
+  {:deprecated "3.8.4"
    :no-doc true}
   (:require [matcher-combinators.core :as core]
             [matcher-combinators.matchers :as matchers]

src/cljc/matcher_combinators/ansi_color.cljc

@@ -8,15 +8,15 @@
   true)
 
 (defn
-  ^{:deprecated true
+  ^{:deprecated "3.8.7"
     :doc "DEPRECATED! Use matcher-combinators.config/enable-ansi-color!"}
   enable!
   []
   #?(:clj (alter-var-root #'*use-color* (constantly true))
      :cljs (set! *use-color* true)))
 
 (defn disable!
-  ^{:deprecated true
+  ^{:deprecated "3.8.7"
     :doc "DEPRECATED! Use matcher-combinators.config/disable-ansi-color!"}
   []
   #?(:clj (alter-var-root #'*use-color* (constantly false))

src/cljc/matcher_combinators/core.cljc

@@ -37,7 +37,7 @@
   (= :match (::result/type match-result)))
 
 (defn
-  ^{:deprecated true
+  ^{:deprecated "2.0.0"
     :doc "DEPRECATED! Use `indicates-match?` instead."}
   match?
   [match-result]

src/cljc/matcher_combinators/test.cljc

@@ -15,19 +15,45 @@
   Commonly, a dev-only user namespace will require this namespace."
   (:require
    #?(:cljs [cljs.test    :as t :refer-macros [is are deftest testing]]
-       :clj  [clojure.test :as t :refer        [is are deftest testing]])
-    #?(:cljs [matcher-combinators.cljs-test]
-       :clj  [matcher-combinators.clj-test])))
-
-(declare ^{:arglists '([matcher actual])}
-         match?)
-(declare ^{:arglists '([type->matcher matcher actual])}
-         match-with?)
-(declare ^{:arglists '([matcher actual]
-                       [exception-class matcher actual])}
-         thrown-match?)
-(declare ^{:arglists '([delta matcher actual])}
-         match-roughly?)
+      :clj  [clojure.test :as t :refer        [is are deftest testing]])
+   #?(:cljs [matcher-combinators.cljs-test]
+      :clj  [matcher-combinators.clj-test])))
+
+(defn match?
+  "Asserts that the `actual` matches the `expected`, where the `expected` can be a value, a predicate function, or a matcher-combinator.
+
+(is (match? [0 1 2] (range 3)))
+(is (match? (complement empty?) (range 3)))
+(is (match? (matcher-combinators.matchers/in-any-order [zero? odd? even?]) (range 3)))"
+  [matcher actual]
+  (throw (#?(:cljs js/Error. :clj AssertionError.)
+          "Should only be invoked within a `clojure.test/is` form")))
+
+(defn match-with?
+  {:deprecated "3.0.0"
+   :doc "DEPRECATED: Use (match? (matcher-combinators.matchers/match-with <type->matcher> <expected>) <actual>) instead."}
+  [type->matcher matcher actual]
+  (throw (#?(:cljs js/Error. :clj AssertionError.)
+          "Should only be invoked within a `clojure.test/is` form")))
+
+(defn thrown-match?
+  "Asserts that evaluating expr throws an exception where the excpetion's ex-data satisfies the provided matcher.
+
+2-arity: (is (thrown-with-match? matcher expr))
+3-arity: (is (thrown-with-match? exception-class matcher expr))"
+  ([matcher actual]
+   (throw (#?(:cljs js/Error. :clj AssertionError.)
+           "Should only be invoked within a `clojure.test/is` form")))
+  ([exception-class matcher actual]
+   (throw (#?(:cljs js/Error. :clj AssertionError.)
+           "Should only be invoked within a `clojure.test/is` form"))))
+
+(defn match-roughly?
+  {:deprecated "3.0.0"
+   :doc "DEPRECATED: Instead use (match? (matcher-combinators.matchers/match-with [number? (matcher-combinators.matchers/within-delta 0.01M)] <expected>) <actual>)"}
+  [delta matcher actual]
+  (throw (#?(:cljs js/Error. :clj AssertionError.)
+          "Should only be invoked within a `clojure.test/is` form")))
 
 #?(:clj
    (def build-match-assert

version.edn

@@ -1,4 +1,4 @@
 {:major 3
  :minor 10
- :release 0
+ :release 1
 #_#_ :qualifier :alpha}