How to document a defmethod function? - clojure

Question

As described in the defmethod doc, they can be given a name. What is very useful in stack traces.
(defmethod foo "a" name-of-method [params] "was a")
When replacing name-of-method by a string. I get the following error:
:cause "Call to clojure.core/fn did not conform to spec."
:data #:clojure.spec.alpha{:problems ({:path [:fn-tail :arity-1 :params], :pred clo
jure.core/vector?, :val "A documentation", :via [:clojure.core.specs.alpha/params+bo
dy :clojure.core.specs.alpha/param-list :clojure.core.specs.alpha/param-list], :in [
0]} {:path [:fn-tail :arity-n], :pred (clojure.core/fn [%] (clojure.core/or (clojure
.core/nil? %) (clojure.core/sequential? %))), :val "A documentation", :via [:clojure
.core.specs.alpha/params+body :clojure.core.specs.alpha/params+body], :in [0]}), :sp
ec #object[clojure.spec.alpha$regex_spec_impl$reify__2509 0x24de08c1 "clojure.spec.a
lpha$regex_spec_impl$reify__2509#24de08c1"]
So what's the propper way to document a defmethod?

Answer 1

You can document the defmethod function using a symbol like the following:
(ns tst.demo.core
(:use tupelo.core tupelo.test))
(defmulti ident
(fn [item] (type item)) )
; vvvvvv-function-name
(defmethod ident clojure.lang.Keyword ident-fn-kw [item]
"to my heart")
(defmethod ident java.lang.String ident-fn-str [item]
"like cheese")
(defmethod ident clojure.lang.Symbol ident-fn-sym [item]
"crash, bang"
;(throw (ex-info "surprise!" {:reason :dont-need-one}))
)
(dotest
(is= clojure.lang.Keyword (spyx (type :hello)))
(is= java.lang.String (spyx (type "hello")))
(is= clojure.lang.Symbol (spyx (type 'hello)))
(is= "to my heart" (ident :hello))
(is= "like cheese" (ident "hello"))
(is= "crash, bang" (ident 'hello))
)
with result:
----------------------------------
Clojure 1.10.1 Java 13-ea
----------------------------------
Testing tst.demo.core
(type :hello) => clojure.lang.Keyword
(type "hello") => java.lang.String
(type (quote hello)) => clojure.lang.Symbol
Ran 2 tests containing 6 assertions.
0 failures, 0 errors.
and if you uncomment the throw you will get the symbol listed in any Exception stacktrace like this:
ERROR in (dotest-line-19) (core.clj:16)
expected: (clojure.core/= "crash, bang" (ident (quote hello)))
actual: clojure.lang.ExceptionInfo: surprise!
{:reason :dont-need-one}
at tst.demo.core$eval23035$ident_fn_sym__23036.doInvoke (core.clj:16)
clojure.lang.RestFn.invoke (RestFn.java:408)
clojure.lang.MultiFn.invoke (MultiFn.java:229)
tst.demo.core$fn__23039.invokeStatic (core.clj:26)
tst.demo.core/fn (core.clj:19)
Notice that the "function name" is included in the stacktrace as tst.demo.core$eval23035$ident_fn_sym__23036. As with any "anonymous" function, this can be of great use in tracking down the cause of an exception. For example:
(dotest
(let [add2 (fn add2-fn [a b] (+ a b))]
(is= 5 (add2 2 3))))
Here we use add2-fn to name the function as a debugging aid in case of an exception. I like to use a -fn suffix as it helps speed grep-based searching of source code.
Update:
Here is the info from clojuredocs.org
;; Methods can be given a name. Very useful in stack traces.
(defmethod foo "a" name-of-method [params] "was a")
So name-of-method is a symbol, not a docstring.
P.S. Note that, to the user, the fact that a function is implemented as a multi-method (vs a regular function with a cond or if or something else), is really just a implementation detail. The contract of the function itself (name, args, purpose, etc) is defined in the defmulti form, and that is where the docstring belongs.