add docstrings to matcher-combinators.test declarations

Author: philomates

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/cljc/matcher_combinators/test.cljc

@@ -15,19 +15,43 @@
   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: 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: 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}