In defn macro, what does an argument starting with caret before the name of a function mean?

Question

In a function definition:

(defn ^boolean =
  ;;other arities omitted...
  ([x y]
    (if (nil? x)
      (nil? y)
      (or (identical? x y)
        ^boolean (-equiv x y))))

what does the ^boolean part in function definition mean? Does it only extend the metadata and signify the type of return, or does it have any deeper meaning? In other words, does it add any more value than simply making the code more self-described?

Answer 1

It is a type hint. See

https://www.safaribooksonline.com/library/view/clojure-programming/9781449310387/ch09s05.html

http://clojure-doc.org/articles/language/functions.html

or your favorite book. PLEASE NOTE: the compiler does not enforce that the actual type matches the type hint! Example w/o type hint:

(defn go []
  "banana" )
(println (go))
;=> banana

(defn ^long go []
  "banana" )
(println (go))
;=> Exception in thread "main" java.lang.ClassCastException: java.lang.String cannot be cast to java.lang.Number,