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

@@ -19,15 +19,26 @@
     #?(:cljs [matcher-combinators.cljs-test]
        :clj  [matcher-combinators.clj-test])))
 
-(declare ^{:arglists '([matcher actual])}
+(declare ^{:arglists '([matcher actual])
+           :doc "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)))"}
          match?)
-(declare ^{:arglists '([type->matcher matcher actual])}
+(declare ^{:arglists '([type->matcher matcher actual])
+           :doc "DEPRECATED: Use (match? (matcher-combinators.matchers/match-with <type->matcher> <expected>) <actual>) instead."}
          match-with?)
 (declare ^{:arglists '([matcher actual]
-                       [exception-class matcher actual])}
+                       [exception-class matcher actual])
+           :doc "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))"}
          thrown-match?)
-(declare ^{:arglists '([delta matcher actual])}
-         match-roughly?)
+(declare ^{:arglists '([delta matcher actual])
+           :doc "DEPRECATED: Instead use (match? (matcher-combinators.matchers/match-with [number? (matcher-combinators.matchers/within-delta 0.01M)] <expected>) <actual>)"}
+ match-roughly?)
 
 #?(:clj
    (def build-match-assert

version.edn

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