This tool can be used to assert that a var's documented usage examples, i.e. doctests, do not speak folly.
Is this useful in Clojure? That's entirely up to you. You might prefer to use comment blocks or :test metadata, or do away with this fluff entirely and live out a happy and care-free existence.
If you like the idea, but take exception to this particular tool, presumably for its lack of pizazz, you may find solace in one of these Clojure libraries that vow to do precisely the same thing:
Scan your ./src directory and generate doctests:
$ clj -m jameslintaylor.doctest
Generated tests in ./target/doctest/
Upon encountering a var with Usage: doc examples, e.g.:
(ns jameslintaylor.doctest.format)
(defmulti form-str
"Given a form, return a formatted string suitable to be written to a
clojure test file.
If form is sequential, the :jameslintaylor.doctest.format/wrap
metadata determines where to begin adding new lines.
Usage:
nil and literal strings are handled appropriately
=> (form-str '(foo nil \"bar\"))
\"(foo nil \"bar\")\"
elements after :jameslintaylor.doctest.format/wrap are on new lines
=> (form-str (wrap 2 '(foo bar baz)))
\"(foo bar\n baz)\""
type)Doctest will generate a corresponding test, e.g.:
(ns jameslintaylor.doctest.format-doctest
"Generated by doctest."
(:require
[clojure.test :refer [deftest is]]
[jameslintaylor.doctest.format :refer [form-str]]))
(deftest ^:doctest form-str-test
(is (= "(foo nil \"bar\")"
(form-str (quote (foo nil "bar"))))
"nil and literal strings are handled appropriately")
(is (= "(foo bar\n baz)"
(form-str (jameslintaylor.doctest.format/wrap 2 (quote (foo bar baz)))))
"elements after :jameslintaylor.doctest.format/wrap are on new lines"))Add ./target/doctest as an extra path to your test runner of choice and run your tests as you would otherwise.